Quickstart

Everything here runs against the sandbox, a mock built from the contract that answers every operation with the examples on these pages. Use synthetic data only. To work offline, run the mock yourself and set BASE=http://localhost:4010.

BASE=https://sandbox.rx.tera.health

Get a brand server token

Brand servers use OAuth client credentials. Keep the secret in your server’s environment, never in code. In the sandbox any client id and secret work.

curl -s $BASE/v1/oauth/token \
  -u "$TERARX_CLIENT_ID:$TERARX_CLIENT_SECRET" \
  -d grant_type=client_credentials \
  -d "scope=enrollments:read enrollments:write"

Platform partners (one client for several brands): add the brand with -d tenant_id=<the brand's id>. Every token is for one brand, so keep one token per brand. GET /v1/tenants lists your brands. See Platform partners.

Copy access_token from the response into TOKEN. It lasts 1 hour; cache it rather than fetching one per call.

TOKEN=trx_at_example_not_a_real_token

Enroll a patient

Call this at checkout. Use one Idempotency-Key per checkout and send the same key on every retry, so a retried checkout can’t enroll twice.

curl -s $BASE/v1/enrollments \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: checkout-ord-2026-10-000123" \
  -d '{
    "external_patient_id": "brand-pt-48213",
    "patient": { "first_name": "Jordan", "last_name": "Rivera", "email": "jordan.rivera@example.com",
      "date_of_birth": "1986-04-12", "sex": "female", "state_code": "NY", "timezone": "America/New_York" }
  }'

The response is the enrollment, with its id and stage.

Get a patient token

Your server signs a short-lived assertion for the patient with your own key, and your app exchanges it for a 15-minute patient token. Platform partners add a tenant_id claim naming the patient’s brand. The patient token sample does both; put its assertion in ASSERTION.

curl -s $BASE/v1/oauth/token \
  -d grant_type=urn:ietf:params:oauth:grant-type:token-exchange \
  -d subject_token=$ASSERTION \
  -d subject_token_type=urn:ietf:params:oauth:token-type:jwt

Then call patient endpoints with that token, starting with GET /v1/patient.

Read clinical flags as the prescriber system

Your prescriber system has its own client with clinical:read and clinical:write. Get its token the same way as in step 1, then list open flags.

curl -s "$BASE/v1/clinical-flags?status=open" -H "Authorization: Bearer $CLINICAL_TOKEN"

Receive webhooks

Verify TeraRx-Signature on the raw body before you trust a delivery. The webhook sample checks the worked example from the Webhooks guide.

Postman

Import the collection and the sandbox environment. Every operation is there with its example, and a pre-request script gets each caller its token: the brand server and the prescriber system with client credentials, the patient by exchanging patient_assertion. For the local mock, set base_url to http://localhost:4010.

Run the mock yourself

Download the bundled spec and start Prism on it:

npx @stoplight/prism-cli@5.16.0 mock openapi.json --port 4010

Then use http://localhost:4010 as the base URL. The samples and the API reference’s playground use it too: pick it in the playground’s server list.

Get started

Guides

Code

Postman

Run the mock yourself

​Postman

​Run the mock yourself

Postman

Run the mock yourself