Enroll a patient

curl --request POST \
  --url https://sandbox.rx.tera.health/v1/enrollments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "plan_code": "ai_health_fitness",
  "external_patient_id": "brand-pt-48213",
  "external_order_id": "ord-2026-10-000123",
  "purchased_at": "2026-10-21T14:58:00Z",
  "patient": {
    "first_name": "Jordan",
    "last_name": "Rivera",
    "email": "jordan.rivera@example.com",
    "phone": "+12025550143",
    "date_of_birth": "1986-04-12",
    "sex": "female",
    "height_cm": 165.1,
    "state_code": "NY",
    "timezone": "America/New_York",
    "units": "imperial",
    "conditions": [
      "prediabetes"
    ],
    "health_profile": {
      "goal_weight_kg": 72.5,
      "activity_level": "lightly_active",
      "food_allergies": [
        "peanuts"
      ],
      "dietary_restrictions": [
        "dairy_free"
      ],
      "food_dislikes": [
        "mushrooms"
      ],
      "cooking": {
        "skill": "beginner",
        "appliances": [
          "stove_range",
          "microwave",
          "air_fryer"
        ],
        "meal_preparer": "mostly_myself"
      },
      "lifestyle": {
        "sleep_hours": 6.5,
        "alcohol": "occasional",
        "smoking": "never"
      }
    }
  },
  "intake": {
    "weight_kg": 96.2,
    "goal_weight_kg": 72.5,
    "activity_level": "lightly_active"
  },
  "consents": [
    {
      "document_code": "coaching_consent",
      "version": "2026-01",
      "accepted_at": "2026-10-21T14:57:30Z",
      "evidence": {
        "ip": "203.0.113.24",
        "checkout_id": "chk_2026_10_000123"
      }
    }
  ],
  "treatment": {
    "medication_id": "6f1d2c3b-4a59-4e8f-9d7c-1b2a3c4d5e6f",
    "dose_mg": 0.25,
    "phase": "titration",
    "injection_weekday": 1,
    "started_on": "2026-09-28"
  }
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    plan_code: 'ai_health_fitness',
    external_patient_id: 'brand-pt-48213',
    external_order_id: 'ord-2026-10-000123',
    purchased_at: '2026-10-21T14:58:00Z',
    patient: {
      first_name: 'Jordan',
      last_name: 'Rivera',
      email: 'jordan.rivera@example.com',
      phone: '+12025550143',
      date_of_birth: '1986-04-12',
      sex: 'female',
      height_cm: 165.1,
      state_code: 'NY',
      timezone: 'America/New_York',
      units: 'imperial',
      conditions: ['prediabetes'],
      health_profile: {
        goal_weight_kg: 72.5,
        activity_level: 'lightly_active',
        food_allergies: ['peanuts'],
        dietary_restrictions: ['dairy_free'],
        food_dislikes: ['mushrooms'],
        cooking: {
          skill: 'beginner',
          appliances: ['stove_range', 'microwave', 'air_fryer'],
          meal_preparer: 'mostly_myself'
        },
        lifestyle: {sleep_hours: 6.5, alcohol: 'occasional', smoking: 'never'}
      }
    },
    intake: {weight_kg: 96.2, goal_weight_kg: 72.5, activity_level: 'lightly_active'},
    consents: [
      {
        document_code: 'coaching_consent',
        version: '2026-01',
        accepted_at: '2026-10-21T14:57:30Z',
        evidence: {ip: '203.0.113.24', checkout_id: 'chk_2026_10_000123'}
      }
    ],
    treatment: {
      medication_id: '6f1d2c3b-4a59-4e8f-9d7c-1b2a3c4d5e6f',
      dose_mg: 0.25,
      phase: 'titration',
      injection_weekday: 1,
      started_on: '2026-09-28'
    }
  })
};

fetch('https://sandbox.rx.tera.health/v1/enrollments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://sandbox.rx.tera.health/v1/enrollments"

payload = {
    "plan_code": "ai_health_fitness",
    "external_patient_id": "brand-pt-48213",
    "external_order_id": "ord-2026-10-000123",
    "purchased_at": "2026-10-21T14:58:00Z",
    "patient": {
        "first_name": "Jordan",
        "last_name": "Rivera",
        "email": "jordan.rivera@example.com",
        "phone": "+12025550143",
        "date_of_birth": "1986-04-12",
        "sex": "female",
        "height_cm": 165.1,
        "state_code": "NY",
        "timezone": "America/New_York",
        "units": "imperial",
        "conditions": ["prediabetes"],
        "health_profile": {
            "goal_weight_kg": 72.5,
            "activity_level": "lightly_active",
            "food_allergies": ["peanuts"],
            "dietary_restrictions": ["dairy_free"],
            "food_dislikes": ["mushrooms"],
            "cooking": {
                "skill": "beginner",
                "appliances": ["stove_range", "microwave", "air_fryer"],
                "meal_preparer": "mostly_myself"
            },
            "lifestyle": {
                "sleep_hours": 6.5,
                "alcohol": "occasional",
                "smoking": "never"
            }
        }
    },
    "intake": {
        "weight_kg": 96.2,
        "goal_weight_kg": 72.5,
        "activity_level": "lightly_active"
    },
    "consents": [
        {
            "document_code": "coaching_consent",
            "version": "2026-01",
            "accepted_at": "2026-10-21T14:57:30Z",
            "evidence": {
                "ip": "203.0.113.24",
                "checkout_id": "chk_2026_10_000123"
            }
        }
    ],
    "treatment": {
        "medication_id": "6f1d2c3b-4a59-4e8f-9d7c-1b2a3c4d5e6f",
        "dose_mg": 0.25,
        "phase": "titration",
        "injection_weekday": 1,
        "started_on": "2026-09-28"
    }
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "id": "0190f5c2-3a1b-7c4d-8e9f-a0b1c2d3e4f5",
  "external_patient_id": "brand-pt-48213",
  "external_order_id": "ord-2026-10-000123",
  "plan_code": "ai_health_fitness",
  "status": "active",
  "stage": "awaiting_assignment",
  "risk_level": "normal",
  "data_sharing": true,
  "purchased_at": "2026-10-21T14:58:00Z",
  "created_at": "2026-10-21T14:58:02Z",
  "assigned_at": null,
  "onboarding_completed_at": null,
  "first_protocol_published_at": null,
  "last_activity_at": null,
  "ended_at": null,
  "care_team": [
    {
      "care_role": "health_coach",
      "assigned": false,
      "assigned_at": null
    },
    {
      "care_role": "fitness_coach",
      "assigned": false,
      "assigned_at": null
    }
  ],
  "forms": [
    {
      "form_assignment_id": "0190f5c3-7e21-7a40-9b11-5d6e7f8091a2",
      "form_code": "glp1_onboarding",
      "purpose": "onboarding",
      "status": "sent",
      "blocks_onboarding": true,
      "due_at": "2026-10-24T15:00:00Z",
      "completed_at": null
    }
  ],
  "protocols": []
}

Enrollments

Enroll a patient

Call this at checkout, or when an existing patient subscribes. In one transaction TeraRx creates the patient record for your brand (or reuses it for a returning patient), the enrollment, the consent records, the first treatment version and the onboarding form assignments from TeraRx’s form rules for your plan, prefilled from intake. On the coached plan it then queues coach assignment for each care role.

Fires enrollment.created, then form.requested per form and, once coaches are assigned, care_team.assigned.

Unique by external_order_id, and by external_patient_id among active and paused enrollments. Error codes: enrollment_exists, external_order_exists (409); plan_not_offered, unknown_medication, unknown_legal_document, validation_failed (422).

Scope: enrollments:write.

POST

enrollments

Enroll a patient

curl --request POST \
  --url https://sandbox.rx.tera.health/v1/enrollments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "plan_code": "ai_health_fitness",
  "external_patient_id": "brand-pt-48213",
  "external_order_id": "ord-2026-10-000123",
  "purchased_at": "2026-10-21T14:58:00Z",
  "patient": {
    "first_name": "Jordan",
    "last_name": "Rivera",
    "email": "jordan.rivera@example.com",
    "phone": "+12025550143",
    "date_of_birth": "1986-04-12",
    "sex": "female",
    "height_cm": 165.1,
    "state_code": "NY",
    "timezone": "America/New_York",
    "units": "imperial",
    "conditions": [
      "prediabetes"
    ],
    "health_profile": {
      "goal_weight_kg": 72.5,
      "activity_level": "lightly_active",
      "food_allergies": [
        "peanuts"
      ],
      "dietary_restrictions": [
        "dairy_free"
      ],
      "food_dislikes": [
        "mushrooms"
      ],
      "cooking": {
        "skill": "beginner",
        "appliances": [
          "stove_range",
          "microwave",
          "air_fryer"
        ],
        "meal_preparer": "mostly_myself"
      },
      "lifestyle": {
        "sleep_hours": 6.5,
        "alcohol": "occasional",
        "smoking": "never"
      }
    }
  },
  "intake": {
    "weight_kg": 96.2,
    "goal_weight_kg": 72.5,
    "activity_level": "lightly_active"
  },
  "consents": [
    {
      "document_code": "coaching_consent",
      "version": "2026-01",
      "accepted_at": "2026-10-21T14:57:30Z",
      "evidence": {
        "ip": "203.0.113.24",
        "checkout_id": "chk_2026_10_000123"
      }
    }
  ],
  "treatment": {
    "medication_id": "6f1d2c3b-4a59-4e8f-9d7c-1b2a3c4d5e6f",
    "dose_mg": 0.25,
    "phase": "titration",
    "injection_weekday": 1,
    "started_on": "2026-09-28"
  }
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    plan_code: 'ai_health_fitness',
    external_patient_id: 'brand-pt-48213',
    external_order_id: 'ord-2026-10-000123',
    purchased_at: '2026-10-21T14:58:00Z',
    patient: {
      first_name: 'Jordan',
      last_name: 'Rivera',
      email: 'jordan.rivera@example.com',
      phone: '+12025550143',
      date_of_birth: '1986-04-12',
      sex: 'female',
      height_cm: 165.1,
      state_code: 'NY',
      timezone: 'America/New_York',
      units: 'imperial',
      conditions: ['prediabetes'],
      health_profile: {
        goal_weight_kg: 72.5,
        activity_level: 'lightly_active',
        food_allergies: ['peanuts'],
        dietary_restrictions: ['dairy_free'],
        food_dislikes: ['mushrooms'],
        cooking: {
          skill: 'beginner',
          appliances: ['stove_range', 'microwave', 'air_fryer'],
          meal_preparer: 'mostly_myself'
        },
        lifestyle: {sleep_hours: 6.5, alcohol: 'occasional', smoking: 'never'}
      }
    },
    intake: {weight_kg: 96.2, goal_weight_kg: 72.5, activity_level: 'lightly_active'},
    consents: [
      {
        document_code: 'coaching_consent',
        version: '2026-01',
        accepted_at: '2026-10-21T14:57:30Z',
        evidence: {ip: '203.0.113.24', checkout_id: 'chk_2026_10_000123'}
      }
    ],
    treatment: {
      medication_id: '6f1d2c3b-4a59-4e8f-9d7c-1b2a3c4d5e6f',
      dose_mg: 0.25,
      phase: 'titration',
      injection_weekday: 1,
      started_on: '2026-09-28'
    }
  })
};

fetch('https://sandbox.rx.tera.health/v1/enrollments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://sandbox.rx.tera.health/v1/enrollments"

payload = {
    "plan_code": "ai_health_fitness",
    "external_patient_id": "brand-pt-48213",
    "external_order_id": "ord-2026-10-000123",
    "purchased_at": "2026-10-21T14:58:00Z",
    "patient": {
        "first_name": "Jordan",
        "last_name": "Rivera",
        "email": "jordan.rivera@example.com",
        "phone": "+12025550143",
        "date_of_birth": "1986-04-12",
        "sex": "female",
        "height_cm": 165.1,
        "state_code": "NY",
        "timezone": "America/New_York",
        "units": "imperial",
        "conditions": ["prediabetes"],
        "health_profile": {
            "goal_weight_kg": 72.5,
            "activity_level": "lightly_active",
            "food_allergies": ["peanuts"],
            "dietary_restrictions": ["dairy_free"],
            "food_dislikes": ["mushrooms"],
            "cooking": {
                "skill": "beginner",
                "appliances": ["stove_range", "microwave", "air_fryer"],
                "meal_preparer": "mostly_myself"
            },
            "lifestyle": {
                "sleep_hours": 6.5,
                "alcohol": "occasional",
                "smoking": "never"
            }
        }
    },
    "intake": {
        "weight_kg": 96.2,
        "goal_weight_kg": 72.5,
        "activity_level": "lightly_active"
    },
    "consents": [
        {
            "document_code": "coaching_consent",
            "version": "2026-01",
            "accepted_at": "2026-10-21T14:57:30Z",
            "evidence": {
                "ip": "203.0.113.24",
                "checkout_id": "chk_2026_10_000123"
            }
        }
    ],
    "treatment": {
        "medication_id": "6f1d2c3b-4a59-4e8f-9d7c-1b2a3c4d5e6f",
        "dose_mg": 0.25,
        "phase": "titration",
        "injection_weekday": 1,
        "started_on": "2026-09-28"
    }
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "id": "0190f5c2-3a1b-7c4d-8e9f-a0b1c2d3e4f5",
  "external_patient_id": "brand-pt-48213",
  "external_order_id": "ord-2026-10-000123",
  "plan_code": "ai_health_fitness",
  "status": "active",
  "stage": "awaiting_assignment",
  "risk_level": "normal",
  "data_sharing": true,
  "purchased_at": "2026-10-21T14:58:00Z",
  "created_at": "2026-10-21T14:58:02Z",
  "assigned_at": null,
  "onboarding_completed_at": null,
  "first_protocol_published_at": null,
  "last_activity_at": null,
  "ended_at": null,
  "care_team": [
    {
      "care_role": "health_coach",
      "assigned": false,
      "assigned_at": null
    },
    {
      "care_role": "fitness_coach",
      "assigned": false,
      "assigned_at": null
    }
  ],
  "forms": [
    {
      "form_assignment_id": "0190f5c3-7e21-7a40-9b11-5d6e7f8091a2",
      "form_code": "glp1_onboarding",
      "purpose": "onboarding",
      "status": "sent",
      "blocks_onboarding": true,
      "due_at": "2026-10-24T15:00:00Z",
      "completed_at": null
    }
  ],
  "protocols": []
}

Authorizations

Authorization

string

header

default:Bearer sandbox_any_token_works

required

A brand's server, one OAuth client per brand and environment. Get a token with the client_credentials grant and send it as Authorization: Bearer <token>. Tokens last 1 hour. A brand server reads status and ids only; it never reads clinical content. A platform partner holds one client for all its brands and gets one token per brand, naming it with tenant_id.

Headers

Idempotency-Key

string

required

A unique key per logical request, for example a UUID. Retrying with the same key and the same body within 24 hours returns the first response (with Idempotent-Replayed: true) instead of creating a duplicate. The same key with a different body is refused with 422 idempotency_key_reused.

Required string length: 8 - 255

Body

application/json

external_patient_id

string

required

Your patient id. It is the sub of the patient assertions you sign later.

Required string length: 1 - 128

Pattern: ^[\x21-\x7E]+$

Example:

"brand-pt-48213"

patient

object

required

What the brand already knows about the patient. Stored on the patient record for this brand only.

Show child attributes

plan_code

enum<string>

Omit to use the brand's default plan.

Available options:

ai_only,

ai_health_fitness

Example:

"ai_health_fitness"

external_order_id

string

Your order id. Unique per brand, so a retried checkout cannot enroll twice.

Required string length: 1 - 128

Pattern: ^[\x21-\x7E]+$

Example:

"ord-2026-10-000123"

purchased_at

string<date-time>

ISO 8601 in UTC.

Example:

"2026-10-26T14:05:00Z"

intake

object

Intake answers you already collected. Keys that match a form field's prefill_from prefill onboarding forms.

Example:

{
  "weight_kg": 96.2,
  "goal_weight_kg": 72.5,
  "activity_level": "lightly_active"
}

consents

object[]

Maximum array length: 20

Show child attributes

treatment

object

The medication, dose and schedule your prescriber set. TeraRx mirrors it and never changes it. Each call adds a version; the latest is the current treatment and earlier ones are the dose history.

Show child attributes

Whether the care team may read this patient's logs. The patient can change it later.

Response

Enrolled.

The brand server's view of an enrollment. Status and ids only, never clinical content.

string<uuid>

required

Example:

"0190f5c2-3a1b-7c4d-8e9f-a0b1c2d3e4f5"

external_patient_id

string

required

Your own identifier, printable ASCII without spaces.

Required string length: 1 - 128

Pattern: ^[\x21-\x7E]+$

Example:

"brand-pt-48213"

plan_code

enum<string>

required

ai_only: the AI Coach only. Escalations go to the brand's prescriber as clinical flags.
ai_health_fitness: the AI Coach plus a health coach (nutrition) and a fitness coach.

Available options:

ai_only,

ai_health_fitness

Example:

"ai_health_fitness"

status

enum<string>

required

Available options:

pending_screening,

ineligible,

active,

paused,

cancelled,

completed

Example:

"active"

stage

enum<string>

required

Available options:

created,

awaiting_assignment,

assigned,

onboarding_pending,

onboarding_completed,

protocols_active

Example:

"onboarding_pending"

risk_level

enum<string>

required

Raised by clinical flags. Only a prescriber's resolve lowers it.

Available options:

normal,

elevated,

high

Example:

"normal"

Example:

true

created_at

string<date-time>

required

ISO 8601 in UTC.

Example:

"2026-10-26T14:05:00Z"

care_team

object[]

required

Empty on ai_only.

Show child attributes

forms

object[]

required

Show child attributes

protocols

object[]

required

Active protocols.

Show child attributes

external_order_id

string | null

Example:

"ord-2026-10-000123"

purchased_at

string<date-time> | null

Example:

"2026-10-21T14:58:00Z"

assigned_at

string<date-time> | null

When the last care role was filled.

Example:

"2026-10-21T15:12:00Z"

onboarding_completed_at

string<date-time> | null

Example:

null

first_protocol_published_at

string<date-time> | null

Example:

null

last_activity_at

string<date-time> | null

Last patient activity, updated about hourly.

Example:

"2026-10-26T13:40:00Z"

ended_at

string<date-time> | null

Example:

null

Auth

Tenants

Enrollments

Treatment

Consent

Brand logs

Events

Reports

Data requests

Patient

Forms

Logging

Progress

Protocols and plans

Meal swap

Library

Care messaging

Feedback

AI Coach

Reminders

Clinical flags

Webhooks

Enroll a patient

Authorizations

Headers

Body

Response