Profile Access API Calls

These API calls allow specially authorized apps to create and access WingCash profiles (users or businesses).

Add a Business

POST /p/add-business

Add a business profile. Requires WingCash Basic App Authentication, so this must be called by server software rather than a mobile device or desktop computer.

App Permission Required

create_profile. See App Permissions.

Request Headers
Request JSON Object
  • manager_uid (string) – Required. The UID of a personal profile that will manage the business. (Note: this field is not required for apps with the temporary add_business_without_manager compatibility flag. That flag is enabled automatically for all apps created before July 2018, but the flag will be phased out. Apps can not get an access token for businesses that have no manager.)
  • business_name (string) – Required. The name of the business. Max 100 characters.
  • dba (string) – Optional. The official DBA (Doing Business As) name of the business. If the business has no officially registered DBA name, this should be left blank. Max 100 characters.
  • web_site (string) – Optional. The URL of the business web site. Max 100 characters.
  • description_html (string) – Optional. A description of the business in HTML format. The HTML will be stripped of everything but basic tags like <p>, <strong>, <em>, <ul>, <ol>, and <li>. Most tag attributes are also stripped, including style attributes. Links (using <a href="...">) are permitted. Max 3000 characters.
  • business (object) –

    Required. The business address. This object has the following attributes:

    public
    Optional. If true, this address will be visible to the public.
    line1
    Required. Max 50 characters.
    line2
    Optional. Max 50 characters.
    suite
    Optional. Max 20 characters.
    city
    Required. Max 50 characters.
    country
    Required. Provide an ISO Alpha-2 code such as US.
    state
    Required for US businesses. Use the capitalized 2 letter abbreviation.
    zip
    Required. Use a postal code outside the US. Max 20 characters.
  • mail (object) – Required. The mailing address. This object has the same attributes as the business field.
  • phone (string) – Optional. The business phone number. Max 20 characters.
  • phone_public (bool) – Optional. If true, the business phone number will be shown to the public.
  • features (object) –

    Optional. Specify which WingCash Features should be enabled for the new profile and when they should expire. The attribute value for each feature must be a JSON object containing enabled (optional bool, defaults to true) and expires (optional string containing an ISO 8601 date with no time). For example, to enable the loyalty feature and the msgset feature, where the msgset feature expires, the features field could be set to:

    {
        "loyalty": {"enabled": true},
        "msgset": {"enabled": true, "expires": "2016-02-03"}
    }
    
Status Codes

Add an Individual

POST /p/add-individual

Add an individual profile. Requires WingCash Basic App Authentication, so this must be called by server software rather than a mobile device or desktop computer.

App Permission Required

create_profile. See App Permissions.

Request Headers
Request JSON Object
  • first_name (string) – Required. The new member’s first name. The first name must be no longer than 50 characters and must start with a letter. Certain Unicode symbols (such as 0x2000 through 0x2fff) are disallowed. Do not use the name of a business as the first or last name.
  • last_name (string) – Required. The new member’s last name. The last name must be no longer than 50 characters and must start with a letter. Certain Unicode symbols (such as 0x2000 through 0x2fff) are disallowed. Do not use the name of a business as the first or last name.
  • business_name (string) – Optional. The name of a business owned by the new member. This field exists to help new members avoid making the mistake of entering a business name in the first and last name fields. If a new member wants to add a business, the member must first create an individual profile with the member’s personal name; WingCash will later prompt the member to add a business. The business name must be no longer than 100 characters. The name may contain most Unicode symbols.
  • agreed_terms_and_privacy (boolean) – Required; must be true. This indicates the new member has agreed to the WingCash member agreement and privacy policy. All user interfaces must ask new members to review the member agreement and privacy policy and indicate their acceptance. Additionally, user interfaces must ask new members to confirm they are at least 18 years of age and that they live in the United States.
  • accepted_policy (boolean) –

    Optional. Set this to true if the individual has already accepted the following policy:

    Like physical cash transfers, transfers through this service are final and non-refundable. Only the recipient can offer refunds, so you should send cash only to people and businesses you trust. This policy is explained in the Terms of Service.

  • weekly_offers (boolean) – Optional. The default is true. Indicates whether the new member would like to receive weekly WingCash offers by email.
  • phone (string) – Optional. If you have the new member’s phone number, provide it here so they don’t have to fill it out again.
  • home (object) –

    Optional JSON object. If you have the new member’s home address, provide it here so they don’t have to fill it out again. The attributes are optional strings containing Unicode without special symbols (such as 0x2000 through 0x2fff).

    line1
    Max 50 characters.
    line2
    Max 50 characters.
    apartment
    Max 20 characters.
    city
    Max 50 characters.
    country
    Provide an ISO Alpha-2 code such as US.
    state
    Use the capitalized 2 letter abbreviation. Leave blank outside the USA.
    zip
    Max 20 characters.
  • features (object) –

    Optional. Specify which WingCash Features should be enabled for the new profile and when they should expire. The attribute value for each feature must be a JSON object containing enabled (optional bool, defaults to true) and expires (optional string containing an ISO 8601 date with no time). For example, to enable the loyalty feature and the msgset feature, where the msgset feature expires, the features field could be set to:

    {
        "loyalty": {"enabled": true},
        "msgset": {"enabled": true, "expires": "2016-02-03"}
    }
    
Status Codes

Get Profile Information by UID

GET /p/get-by-uid

Get profile information based on an email address, phone number, WingCash username, or profile ID. Requires WingCash Basic App Authentication, so this must be called by server software rather than a mobile device or desktop computer.

Apps can only get information about profiles belonging to the same site as the site accessed by the app.

App Permission Required

get_profile. See App Permissions.

Request Headers
Query Parameters
  • uid

    Required. The UID to look up. Some examples:

    • email:Some.Person+Here@example.com
    • phone:+12025550111 (Phone numbers must be in E.164 format.)
    • username:sample1
Status Codes
  • 200 OK

    If the profile was found, the response body is a JSON object with a profile attribute containing a Profile object. The profile object includes the confirmed_uids attribute, similar to a ProfileDetail object.

    If no matching profile was found, or the profile belongs to a different site, the response body is a JSON object with no profile attribute.

  • 400 Bad Request – A parameter was invalid or incorrect. See InvalidRequest.
  • 401 Unauthorized – The authentication credentials were missing or incorrect.
  • 403 Forbidden – The app does not have permission to use this call. The response body will have more details.

Get an Access Token for Controlling a Profile

POST /p/token

Get an access token for controlling a profile. Once the app has an access token for a profile, the app can use the WingCash API to send cash, view history, and change the profile’s settings.

Access tokens generated this way can send only closed loop cash, not open loop cash. Also, apps can only generate access tokens for profiles belonging to the same site as the site accessed by the app.

Requires WingCash Basic App Authentication, so this must be called by server software rather than a mobile device or desktop computer.

Note

This API call assumes your service has already authenticated the user. If you have not authenticated the user and would like WingCash to send an authentication email or SMS, try the POST /aa/signin-closed API call.

App Permission Required

control_profile. See App Permissions.

Request Headers
Request JSON Object
  • uid (string) –

    Required. A UID of the profile to access. Some examples:

    • wingcash:1010101
    • email:Some.Person+Here@example.com
    • phone:+12025550111 (Phone numbers must be in E.164 format.)
    • username:sample1
  • manager_uid (string) – Required when getting an access token for a business. Provide the UID of a personal profile that manages the business and belongs to the same site. Apps should normally provide the same manager_uid in this API call as the manager_uid provided to the POST /p/add-business call.
  • concurrent (bool) –

    Optional. Enable this field if your app needs multiple concurrent access tokens for a single profile. Apps that generate a new access token for every operation usually need concurrent access tokens, while apps that cache access tokens usually don’t need concurrent access tokens.

    The first use of an access token normally invalidates all other access tokens for the same app, profile, personal profile, and device. Concurrent access tokens, on the other hand, are not invalidated when the app uses other access tokens, allowing the app to use multiple access tokens without coordination.

    To maintain security, concurrent access tokens have a short-lived hard expiration (15 minutes by default.) If your app refreshes a concurrent access token, the new token will expire at the same time as the original.

  • device_name (string) – Optional. The name of the device calling this API. If not provided, the device name will be derived from the User-Agent HTTP header.
  • device_uuid (string) – Optional UUID for the device. If the device UUID is provided, the device will be attached to the user’s profile. A randomly generated UUID is acceptable. The UUID should be persisted on the device and reused for future API calls. Limited to 36 characters.
  • permissions (list) –

    Optional list of permission name strings. Provide the list of Permissions the access token needs to use. If the permission list is not provided, the token will have a default permission list appropriate for sending and receiving closed loop cash.

    The permissions field only limits which permissions your app can attempt to use; the permissions field never directly grants access to information or resources. For example, if you want to edit a cash design using the API, you can use the /p/token call to get an access token for a profile that already has the right to edit your cash design; specify in the /p/token call that your access token needs to use the edit_design permission. If you don’t, your access token will not have permission to edit the cash design even though the profile can.

    The token-specific permission list is intended to help you maintain security through the principle of least privilege. Also, WingCash keeps a record of all permissions used by an app and presents the list to users. Users are encouraged to remove and block apps that are using unnecessary permissions.

Status Codes

Get the Features for a Profile

GET /p/(string: profile_id)/features

Get an object that lists which WingCash Features the specified profile has.

Requires WingCash Basic App Authentication, so this must be called by server software rather than a mobile device or desktop computer. If the profile does not belong to the site through which the API was accessed, a 403 response will be returned.

App Permission Required

control_profile. See App Permissions.

Request Headers
Status Codes
  • 200 OK – Successful. The response body is a JSON object containing an attribute for each enabled feature. The attribute value for each feature is a JSON object that may contain expires (an ISO 8601 date with no time).
  • 400 Bad Request – A parameter was invalid or incorrect. See InvalidRequest.
  • 401 Unauthorized – The authentication credentials were missing or incorrect.
  • 403 Forbidden – The app does not have permission to use this call. The response body will have more details.

Change the Features for a Profile

PATCH /p/(string: profile_id)/features

Change the features available to the specified profile. Only the features listed in the Features documentation may be enabled or disabled.

Requires WingCash Basic App Authentication, so this must be called by server software rather than a mobile device or desktop computer. If the profile does not belong to the site through which the API was accessed, a 403 response will be returned.

App Permission Required

control_profile. See App Permissions.

Request Headers
Request JSON Object
  • {}

    Specify which WingCash Features should be enabled or disabled for the profile and when they should expire. The attribute value for each feature must be a JSON object containing enabled (optional bool, defaults to true) and expires (optional string containing an ISO 8601 date with no time). For example, to enable the loyalty feature and the msgset feature, where the msgset feature expires, the body of the request could be set to:

    {
        "loyalty": {"enabled": true},
        "msgset": {"enabled": true, "expires": "2016-02-03"}
    }
    
Status Codes
  • 200 OK – Successful. The response body is a JSON object containing an attribute for each enabled feature. The attribute value for each feature is a JSON object that may contain expires (an ISO 8601 date with no time).
  • 400 Bad Request – A parameter was invalid or incorrect. See InvalidRequest.
  • 401 Unauthorized – The authentication credentials were missing or incorrect.
  • 403 Forbidden – The app does not have permission to use this call. The response body will have more details.