Getting Started

This guide walks through a small end-to-end InsideTracker integration path. By the end, your backend can authenticate, create a User, store customer-level credentials, submit basic User data, and retrieve a personalized biomarker output.

This first path makes the User-level workflow concrete, then points you to the next guide for the workflow you are building.

Authenticate

Request a service-level token, then use customer-level tokens for User-specific work.

Add User data

Create the User, store their identifiers, and submit profile and blood result data.

Retrieve an output

Fetch a personalized biomarker output to confirm the User-level flow is working.

Before You Begin

You need the following from InsideTracker:

Requirement	Why you need it
Partner account access	Required to access InsideTracker APIs.
Client ID and client secret	Required to request service-level tokens.
Sandbox environment access	Used to build and test before production.
API Reference access	Used for exact endpoint schemas and examples.

Use the sandbox base URL while building and testing:

https://api.sandbox.insidetracker.com

For authenticated requests, send the access token in the Authorization header:

Authorization: Bearer {access_token}

How Authentication Works

InsideTracker uses two authentication levels in a typical integration.

A service-level token lets your backend act as your organization.

Use it for Partner-level operations, such as creating Users, recovering User tokens, and managing organization resources.

Store refresh tokens securely and refresh access tokens before they expire. Do not expose service-level or customer-level tokens to client-side applications unless your architecture has been reviewed for that use case.

Step 1: Authenticate Your Service

Start by requesting a service-level access token.

POST /oauth/token
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "{client_id}",
  "client_secret": "{client_secret}",
  "audience": "customer_api"
}

The response includes a service-level access token:

{
  "access_token": "{service_access_token}",
  "token_type": "Bearer",
  "refresh_token": "{refresh_token}",
  "expires_in": 3600
}

Use this token for service-level API requests.

Step 2: Create A User

Create a linked InsideTracker customer record for the User. The customer creation endpoint is batch-oriented, so a single-User request still sends an array with one item.

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

[
  {
    "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"
    }
  }
]

For each User in the response, check the item-level result.

Field	What to do with it
`extId`	Store this as the stable mapping between your User and the linked InsideTracker customer record.
`credentials.accessToken`	Store securely and use for customer-level requests for this User.
`credentials.refreshToken`	Store securely and use to refresh the User's customer-level token.
`succeed`	Check this for each item. A batch response can include both successful and failed Users.
`errors`	Log and handle item-level validation failures.

Do not rely only on the HTTP status code for User creation. Check each response item so your integration can handle partial success.

Step 3: Store User Credentials

After User creation, store the values your system needs for future User-level operations.

Value	Required?	Notes
Your User ID	Yes	Your internal identifier for the User.
`extId`	Yes	The identifier used to map your User to the linked InsideTracker customer record.
Customer access token	Yes	Used for User-specific API requests until it expires.
Customer refresh token	Yes	Used to refresh the User's customer-level access token.

Treat these values as sensitive. They connect your User to health-related data and User-specific operations.

Step 4: Add Profile Data

Profile and onboarding data help InsideTracker personalize outputs for the User. A simple first path can include physiomarker data such as height, weight, body composition, and resting heart rate.

POST /api/pages/physioMarkers/physioMarkersPost
Content-Type: application/json
Authorization: Bearer {customer_access_token}

{
  "bodyFatPercent": 25.5,
  "waist": 32,
  "hip": 38,
  "weight": 150,
  "height1": 5,
  "height2": 8,
  "rhr": 65
}

The expected measurement system depends on the User's account settings. Send values in the units expected for that User.

Step 5: Add A Structured Blood Result

For this first path, submit a structured blood result with marker values. The Add Blood Result guide covers marker preparation, markerId mapping, result retrieval, and update behavior in more detail.

At a high level:

Confirm which markers are available for upload.
Submit the result with testDate, countryCode, and markerValues.
Store the returned resultId.

Submit the result with a customer-level token:

POST /api/customer/v1/blood/results-upload/add-result
Content-Type: application/json
Authorization: Bearer {customer_access_token}

{
  "testDate": "2026-05-01",
  "countryCode": "US",
  "markerValues": [
    {
      "markerId": 17,
      "value": 95.0
    }
  ]
}

Store the returned resultId if your workflow needs to inspect, update, or troubleshoot the result later.

Step 6: Retrieve A Personalized Biomarker Output

After adding User data, retrieve personalized blood marker ranges for the User.

GET /api/customer/blood/ranges
Authorization: Bearer {customer_access_token}

The response contains marker-specific range boundaries:

{
  "items": [
    {
      "markerId": 123,
      "markerAbbr": "Glu",
      "minBorderLine": 70,
      "minNearNormal": 75,
      "minA": 80,
      "minG": 85,
      "maxG": 95,
      "maxA": 100,
      "maxNearNormal": 110,
      "maxBorderLine": 125
    }
  ]
}

This confirms that the User-level flow is working: InsideTracker can receive User data and return personalized biomarker context.

If Your First Workflow Is Different

Some integrations should start with a different data onboarding path.

If you need to...	Start with
Upload PDF or image blood result documents	Blood Result Upload and OCR Blood Result Upload
Submit marker values directly	Add Blood Result
Order a Quest or Mobile Blood Draw lab test	Lab Connect
Register Fitbit data access	Connecting Wearable Devices
Submit Apple HealthKit data from a User device	Connecting Wearable Devices
Retrieve recommendations or build adherence tracking	Recommendations and Action Plan
Retrieve timely insights that reinforce recommended actions	ProTips
Update account-level fields after User creation	Customer Account Management

Implementation Checklist

First path checklist

You can request a service-level access token.
You can create a User through the customer creation endpoint.
You check item-level success and errors from batch User-creation responses.
You store the User's extId, customer access token, and customer refresh token securely.
You can make customer-level requests for the User.
You can add profile or physiomarker data.
You can add a structured blood result.
You can retrieve personalized blood marker ranges.
Your system refreshes tokens before access tokens expire.

Related Guides

Authorization and Security
Creating Users
Customer Account Management
Adding Profile Data
Add Blood Result
Blood Result Upload
Lab Connect
Connecting Wearable Devices
ProTips
Webhooks

Related API Reference

Use the API Reference for endpoint-level schemas, status codes, and full request and response examples:

POST /oauth/token
POST /enterprise/customers/sa/v1/customers
POST /api/pages/physioMarkers/physioMarkersPost
GET /api/customer/blood/results-upload/available-markers-for-new-result
POST /api/customer/v1/blood/results-upload/add-result
GET /api/customer/blood/ranges