Creating Users

You own the User relationship in your product or service. In these docs, creating Users means creating linked InsideTracker customer records for those Users.

That linked customer record gives InsideTracker a place to attach User data, generate User-specific outputs, and return a customer-level token pair for future User-specific API calls.

Create linked records

Send one or more Users to the customer creation endpoint.

Store the mapping

Store extId so your system can connect each User to the InsideTracker customer record.

Store credentials

Store customer-level access and refresh tokens securely for future User-specific calls.

Where This Fits

Use this page when you have a service-level token and are ready to create linked InsideTracker customer records for your Users.

The output of this step is the durable User mapping and customer-level credentials your backend uses for later User-specific workflows.

Before You Begin

Requirement	Why you need it
Service-level access token	Required to call the customer creation endpoint.
User identity data	Required to create the linked customer record.
Secure token storage	Required because successful creation returns customer-level credentials.
User mapping strategy	Required to connect your User record to the InsideTracker customer record.

Use the sandbox environment while building and testing:

https://api.sandbox.insidetracker.com

Endpoint

POST /enterprise/customers/sa/v1/customers
Content-Type: application/json
Authorization: Bearer {service_access_token}

The endpoint creates customer records in batch mode. The current public API reference supports up to 1,000 customer records in one request. To create one linked customer record, send an array with one User object.

Request Body

[
  {
    "extId": "b2d905cd-e5ff-4843-817e-cc27a916c90c",
    "firstName": "Jordan",
    "lastName": "Example",
    "email": "[email protected]",
    "phone": "+15551234567",
    "birthdate": "1990-01-25",
    "biologicalSex": "FEMALE",
    "ethnicity": "asian",
    "measurementSystem": "IMPERIAL",
    "timezone": "America/New_York",
    "heightCm": 167.6,
    "weightKg": 68.0,
    "address": {
      "address1": "123 Main St",
      "address2": "Apt 2",
      "city": "Boston",
      "state": "MA",
      "country": "US",
      "zip": "02124"
    }
  }
]

Request Fields

Field	Required?	Description
`firstName`	Required	User's first name.
`lastName`	Required	User's last name.
`email`	Required	User's email address.
`phone`	Required	User's phone number. Use a `+` followed by digits.
`birthdate`	Required	User's birthdate in `YYYY-MM-DD` format.
`biologicalSex`	Required	Allowed values: `MALE`, `FEMALE`.
`ethnicity`	Required	User's ethnicity value. Use the API Reference for the current allowed values.
`measurementSystem`	Required	User's preferred measurement system. Allowed values: `METRIC`, `IMPERIAL`.
`extId`	Optional	External UUID to attach to the customer record. If omitted, InsideTracker generates one.
`timezone`	Optional	User's timezone.
`heightCm`	Optional	User's height in centimeters.
`weightKg`	Optional	User's weight in kilograms.
`address`	Optional	User's address information.

Provide your own stable extId when possible. If InsideTracker generates extId, store the returned value before making additional User-specific requests.

Response

The response contains one result for each submitted User object.

[
  {
    "credentials": {
      "accessToken": "{customer_access_token}",
      "refreshToken": "{customer_refresh_token}"
    },
    "email": "[email protected]",
    "errors": [],
    "extId": "b2d905cd-e5ff-4843-817e-cc27a916c90c",
    "succeed": true
  }
]

For each response item:

Field	What to do with it
`succeed`	Check whether that customer record was created successfully.
`errors`	Handle validation or processing errors for that item.
`extId`	Store as the durable mapping between your User and the InsideTracker customer record.
`credentials.accessToken`	Store securely and use for customer-level API requests.
`credentials.refreshToken`	Store securely and use to refresh the User's customer-level access token.

Batch Behavior

The endpoint returns one response item for each submitted User object. A request can return HTTP 200 even when one or more individual records failed validation.

Always inspect succeed and errors for each response item. Do not treat the HTTP status alone as proof that every linked customer record was created.

Store The Mapping

After successful creation, store:

Value	Why it matters
Your internal User ID	Lets your system find the User.
`extId`	Maps your User to the linked InsideTracker customer record.
Customer access token	Lets your backend make User-specific API requests until the token expires.
Customer refresh token	Lets your backend refresh customer-level access.

Treat customer credentials as sensitive data. Store them server-side and do not expose them in browser or mobile code unless that architecture has been reviewed for your integration.

When Creation Fails

If succeed is false, inspect the errors array for that response item. Common causes include:

Missing required fields.
Invalid field formats, such as an invalid phone number or birthdate.
Unsupported enum values.
Duplicate or invalid extId.

Log enough information to troubleshoot the request, but do not log access tokens, refresh tokens, or unnecessary personal data.

Token Recovery

If the customer token pair is lost or broken, use the token recovery endpoint with a service-level token:

POST /enterprise/customers/sa/v1/customers/recreate-tokens
Content-Type: application/json
Authorization: Bearer {service_access_token}

[
  {
    "extId": "b2d905cd-e5ff-4843-817e-cc27a916c90c"
  }
]

Use token recovery only when the current customer token pair cannot be refreshed or used. In normal operation, refresh the customer token with the stored customer refresh token.

Implementation checklist

You request a service-level token before calling the customer creation endpoint.
You send User records as an array, even when creating one linked customer record.
You provide required identity and demographic fields.
You check succeed and errors for every item in the response.
You store the returned extId.
You store customer access and refresh tokens securely.
You use customer-level tokens for future User-specific API requests.
You have a recovery path for lost or broken customer token pairs.

Related Guides

Authorization and Security
Getting Started
Adding Profile Data

Related API Reference

POST /enterprise/customers/sa/v1/customers
POST /enterprise/customers/sa/v1/customers/recreate-tokens