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.
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.
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: