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