SSO Payload

Both the Component Auth and Get Token flows describe the user and their company using the same JSON schema — this page documents it for both.

Example

{
  "name": "John Doe",
  "firstName": "John",
  "lastName": "Doe",
  "email": "[email protected]",
  "externalId": "123456",
  "isActive": true,
  "language": "en-US",
  "accountData": [
    {
      "type": 0,
      "name": "Acme Corporation",
      "mobilePhone": "+1 334-123-4567",
      "email": "[email protected]",
      "alpha3Code": "USA",
      "externalId": "7890",
      "isActiveCompany": true,
      "identifier": [
        { "value": "123-45-6789", "type": "SSN" }
      ],
      "companyIndustry": "Oilseed and Grain Combination Farming",
      "annualRevenue": "500,000",
      "numberOfBusinessLocations": "1",
      "numberOfEmployees": "20",
      "address": {
        "street": "13785 Research Blvd",
        "streetNumber": "Suite 150",
        "city": "Montgomery",
        "state": "AL",
        "zip": "10000",
        "addressType": "1",
        "countryIsoCode": 840
      },
      "phones": [
        { "countryCode": 840, "cityOrAreaCode": 334, "localNumber": 1234567, "phoneTypeName": "1" }
      ]
    }
  ]
}

📘
What's Actually Required
Business Health needs externalId or email (at least one of the two) to identify the user — that's the only hard requirement. Everything else is optional at the API level.
That said, we strongly recommend also providing isActive, name, accountData.name, and accountData.externalId — without them, Business Health has very little to work with when creating or displaying the user's record, and results may not look the way you expect.
One default worth knowing: if isActive is omitted, it defaults to false, and the user is created (or updated) as inactive.

Parameters

Name	Type	Description
`name`	String	(Recommended) Full name of the user.
`firstName`	String	(Optional) First name of the user.
`lastName`	String	(Optional) Last name of the user.
`email`	String	(One of `email` / `externalId` required) Email address of the user.
`externalId`	String	(One of `email` / `externalId` required) Unique identifier of the user in your platform.
`isActive`	Boolean	(Recommended) Whether the user is active in your platform and should be active in Business Health. Defaults to `false` if omitted.
`language`	String	(Optional) The user's locale code. Expected format: `en-US`.
`accountData`	Array	(Optional) Companies or other legal entities related to the user. May also contain related addresses and phone numbers.
`accountData` `.type`	Integer	(Optional) Type of the user's company. Recommended value: `0`.
`accountData` `.name`	String	(Recommended) Name of the user's company.
`accountData` `.mobilePhone`	String	(Optional) Cell phone number of the user's company.
`accountData` `.email`	String	(Optional) Email address of the user's company.
`accountData` `.alpha3Code`	String	(Optional) Three-letter country code of the user's company.
`accountData` `.externalId`	String	(Recommended) Unique identifier of the user's company in your platform.
`accountData` `.isActiveCompany`	Boolean	(Optional) Relevant if the user has multiple companies. `true` if this company is the one currently selected in your platform, and its data should be shown in the widgets; `false` otherwise.
`accountData` `.identifier`	Array	(Optional) Parameters that uniquely identify the user's company.
`accountData` `.identifier.value`	String	(Optional) Value of the identifying parameter — for example, an SSN.
`accountData` `.identifier.type`	String	(Optional) Type of the identifying parameter: `SSN` (Social Security Number), `EIN` (Employer Identification Number), or `ITIN` (tax processing number for individuals not eligible for an SSN). Contact UPTIQ if you need other identifier types configured, including for countries outside the U.S.
`accountData` `.companyIndustry`	String	(Optional) The company's industry, per the North American Industry Classification System (NAICS) — numeric code or title, any aggregation level. Contact UPTIQ if you need other industry classifications, including for countries outside the U.S.
`accountData` `.annualRevenue`	String	(Optional) Company's annual revenue.
`accountData` `.numberOfBusinessLocations`	String	(Optional) Number of the company's locations.
`accountData` `.numberOfEmployees`	String	(Optional) Number of the company's employees.
`accountData` `.address`	Object	(Optional) Company's address.
`accountData` `.address.street`	String	(Optional) Building number and street name.
`accountData` `.address.streetNumber`	String	(Optional) Apartment or suite number.
`accountData` `.address.city`	String	(Optional) City where the company is registered.
`accountData` `.address.state`	String	(Optional) State where the company is registered.
`accountData` `.address.zip`	String	(Optional) Zip or postal code.
`accountData` `.address.addressType`	String	(Optional) `1` – Business, `2` – Home, `3` – Other, `4` – Bill Payee.
`accountData` `.address.countryIsoCode`	Integer	(Optional) Numeric country code per ISO 3166.
`accountData.phones`	Array	(Optional) Company's phone number(s).
`accountData` `.phones.countryCode`	Integer	(Optional) Numeric country code per ISO 3166.
`accountData` `.phones.cityOrAreaCode`	Integer	(Optional) City or area code.
`accountData` `.phones.localNumber`	Integer	(Optional) The phone number itself.
`accountData` `.phones.phoneTypeName`	String	(Optional) `1` – Business, `2` – Car, `3` – Home, `4` – Mobile, `5` – Pager, `6` – TDD, `7` – Other, `8` – Fax.