Skip to main content
Start here. Every other page assumes you have a working token and know which host to call.

What you’ll do

1

Point at the right host

Build against staging, with the credentials issued for it.
2

Exchange your credentials for a token

POST /v0.1/auth/token with a JSON body, then read data.access_token.
3

Call a resource endpoint

Send the token as a bearer header and read the items / data envelope back.
4

Run your first five calls

Confirm your tenant is provisioned before you write any integration code.

Hosts

The partner surface is /v0.1

Every resource you need is under /v0.1 — patients, questionnaires, questionnaire-responses, encounters, products, prices, checkouts, orders, subscriptions. That includes authentication: the token endpoint is /v0.1/auth/token. /v1 paths are not part of the partner surface — do not call them.

Recipe 1.2 · Your first five calls

Run these in order before writing any integration code. If any fails, stop and report it — the rest of the cookbook assumes they pass.
  1. POST /v0.1/auth/token → 200, and data.access_token is present
  2. GET /v0.1/patients → 200 with an items array
  3. GET /v0.1/questionnaires?status=active → 200, and at least one form
  4. GET /v0.1/products?active=true → 200, and at least one product
  5. GET /v0.1/configs → 200, with a payment provider and an active status
Steps 3 and 4 depend on your tenant being seeded. An empty result is not a bug in your code — see Known gaps and staging.
Locked by check first-five-calls.

Call 1 — the token exchange

Client-credentials, JSON body — not form-encoded.
audience is a fixed string, not the host you are calling. Use the audience value from the Hosts table above even when you are calling api-staging. Setting it to the staging host will fail.
The token is nested under data, matching the published AuthTokenResponse schema. Read expires_in rather than hard-coding a lifetime — it differs between environments, and production tokens are short-lived. Refresh before expiry; do not retry on 401 without re-exchanging.

Calls 2 to 5 — send the token

Send it as a bearer token on every call:

What comes back

Collections return an items array. Clinical resources page with an after cursor (present only when there is a next page). The product catalogue carries a pagination object, but catalogue paging is not implemented yet, so do not build a cursor loop on it. Do not write one shared pagination helper — see API status, “Response envelopes differ by endpoint”, for the full picture.
Writes return the created resource under data, not items:
Locked by check writes-return-data-reads-return-items.
Errors carry a message and a code:
Always log request_id. It is on every response, success or failure, and it is the fastest way for support to find your exact call. A problem report without one usually costs a round trip.
Locked by check request-id-on-success-and-failure.

Gotchas

Staging and production use different credentials. A client id/secret pair issued for one environment will not authenticate against the other. A staging credential presented to the production host is also rejected at the gateway with a misleading error — keep the two configurations separate from the start.
audience is not the host — see FAQ and troubleshooting if that distinction is unclear.
Reading an error correctly. Three different failures all arrive as 403, and they need different responses from you:

Start here

The seven stages in build order, what to read first, and the reference pages

Integration flow

The whole journey — patient, intake, encounter, payment — as a sequence

Errors

When a call here fails: the error envelope, and what each status means by endpoint family