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.POST /v0.1/auth/token→200, anddata.access_tokenis presentGET /v0.1/patients→200with anitemsarrayGET /v0.1/questionnaires?status=active→200, and at least one formGET /v0.1/products?active=true→200, and at least one productGET /v0.1/configs→200, with a payment provider and an active status
Locked by check
first-five-calls.Call 1 — the token exchange
Client-credentials, JSON body — not form-encoded.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.
data, not items:
Locked by check
writes-return-data-reads-return-items.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
audience is not the host — see FAQ and troubleshooting if that distinction is unclear.403, and they need
different responses from you:
Related
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

