Onboarding reference data

Use these three read-only calls to fill pickers in an onboarding form. They return static lists, so you can cache them.

• Location affects tax jurisdiction and the compliance requirements that apply.
• A Merchant Category Code (MCC) classifies the type of business or service an Account provides.
• Occupation selection can affect tax classification or compliance requirements.

Prerequisites

• A credential for a Person, an Account session, or a ServiceAccount with access to reference data. All three calls are Account-scoped, so X-Wingspan-Account is accepted when you act on a child Account. See Acting on behalf of Accounts.

Endpoints

listLocations and listOccupations take page[size] (1 to 100, default 25) and page[token]. Follow pagination.nextPageToken until it's an empty string. listMccCodes has no page parameter and its response has no pagination object.

Response fields

Each item carries accountId (the owning Account) plus:

Example: list locations

curl "https://api.wingspan.app/v3/onboarding/locations?page[size]=2" \
  -H "Authorization: Bearer $WINGSPAN_TOKEN"

// 200 OK (trimmed)
{
  "url": "/v3/onboarding/locations",
  "data": [
    { "accountId": "Nw7kQ2pLx9RtVb3mHc5dZa", "code": "US-TX", "name": "Texas", "country": "US", "subdivision": "TX" }
  ],
  "pagination": { "nextPageToken": "" }
}

listMccCodes returns { "url": "...", "data": [ { "code": "5734", "name": "Computer Software Stores", "category": "Technology" } ] }.

Errors

Related pages

• Identity verification shows where location and tax fields are collected.