Update the patient's details

curl --request PATCH \
  --url https://sandbox.rx.tera.health/v1/enrollments/{enrollment_id}/patient \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/merge-patch+json' \
  --data '
{
  "phone": "+12025550178",
  "state_code": "NJ",
  "health_profile": {
    "food_allergies": [
      "peanuts",
      "sesame"
    ]
  }
}
'

const options = {
  method: 'PATCH',
  headers: {
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/merge-patch+json'
  },
  body: JSON.stringify({
    phone: '+12025550178',
    state_code: 'NJ',
    health_profile: {food_allergies: ['peanuts', 'sesame']}
  })
};

fetch('https://sandbox.rx.tera.health/v1/enrollments/{enrollment_id}/patient', 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/{enrollment_id}/patient"

payload = {
    "phone": "+12025550178",
    "state_code": "NJ",
    "health_profile": { "food_allergies": ["peanuts", "sesame"] }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/merge-patch+json"
}

response = requests.patch(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": "protocols_active",
  "risk_level": "normal",
  "data_sharing": true,
  "purchased_at": "2026-10-21T14:58:00Z",
  "created_at": "2026-10-21T14:58:02Z",
  "assigned_at": "2026-10-21T15:12:00Z",
  "onboarding_completed_at": "2026-10-22T09:30:00Z",
  "first_protocol_published_at": "2026-10-23T16:45:00Z",
  "last_activity_at": "2026-10-26T13:40:00Z",
  "ended_at": null,
  "care_team": [
    {
      "care_role": "health_coach",
      "assigned": false,
      "assigned_at": null
    },
    {
      "care_role": "fitness_coach",
      "assigned": true,
      "assigned_at": "2026-10-21T15:12:00Z"
    }
  ],
  "forms": [],
  "protocols": [
    {
      "protocol_id": "0190f5c6-8b9c-7d01-8e23-4f5a6b7c8d90",
      "type": "nutrition",
      "version": 1,
      "published_at": "2026-10-23T16:45:00Z"
    }
  ]
}

Enrollments

Update the patient's details

Contact details, demographics, time zone, conditions and the health profile, when they change in your system. Changes reach the care team at once and apply to plans and AI Coach replies generated after them.

A new state_code matters: coaches are licensed per state. A coach not licensed in the new state is taken off the patient and a licensed one is found, so you get care_team.changed with reason_code: state_change (or care_team.capacity_warning if none is free). Until then that role shows assigned: false in the response.

Error codes: enrollment_not_active (409) for a cancelled or completed enrollment, validation_failed (422).

Scope: enrollments:write.

PATCH

enrollments

{enrollment_id}

patient

Update the patient's details

curl --request PATCH \
  --url https://sandbox.rx.tera.health/v1/enrollments/{enrollment_id}/patient \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/merge-patch+json' \
  --data '
{
  "phone": "+12025550178",
  "state_code": "NJ",
  "health_profile": {
    "food_allergies": [
      "peanuts",
      "sesame"
    ]
  }
}
'

const options = {
  method: 'PATCH',
  headers: {
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/merge-patch+json'
  },
  body: JSON.stringify({
    phone: '+12025550178',
    state_code: 'NJ',
    health_profile: {food_allergies: ['peanuts', 'sesame']}
  })
};

fetch('https://sandbox.rx.tera.health/v1/enrollments/{enrollment_id}/patient', 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/{enrollment_id}/patient"

payload = {
    "phone": "+12025550178",
    "state_code": "NJ",
    "health_profile": { "food_allergies": ["peanuts", "sesame"] }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/merge-patch+json"
}

response = requests.patch(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": "protocols_active",
  "risk_level": "normal",
  "data_sharing": true,
  "purchased_at": "2026-10-21T14:58:00Z",
  "created_at": "2026-10-21T14:58:02Z",
  "assigned_at": "2026-10-21T15:12:00Z",
  "onboarding_completed_at": "2026-10-22T09:30:00Z",
  "first_protocol_published_at": "2026-10-23T16:45:00Z",
  "last_activity_at": "2026-10-26T13:40:00Z",
  "ended_at": null,
  "care_team": [
    {
      "care_role": "health_coach",
      "assigned": false,
      "assigned_at": null
    },
    {
      "care_role": "fitness_coach",
      "assigned": true,
      "assigned_at": "2026-10-21T15:12:00Z"
    }
  ],
  "forms": [],
  "protocols": [
    {
      "protocol_id": "0190f5c6-8b9c-7d01-8e23-4f5a6b7c8d90",
      "type": "nutrition",
      "version": 1,
      "published_at": "2026-10-23T16:45:00Z"
    }
  ]
}

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.

Path Parameters

enrollment_id

string<uuid>

required

Body

application/merge-patch+json

JSON Merge Patch (RFC 7396) of the patient's details. Send only the fields that changed: the patient edits some of them too (height, units, the health profile), and the last write wins. health_profile merges key by key.

first_name

string

Maximum string length: 100

Example:

"Jordan"

last_name

string

Maximum string length: 100

Example:

"Rivera"

string<email>

Maximum string length: 254

Example:

"jordan.rivera@example.com"

phone

string

E.164.

Pattern: ^\+[1-9][0-9]{7,14}$

Example:

"+12025550143"

date_of_birth

string<date>

Example:

"1986-04-12"

sex

enum<string>

Available options:

female,

male,

intersex

Example:

"female"

height_cm

number

Required range: 50 <= x <= 260

Example:

165.1

state_code

string

US state of residence (USPS code). Decides which licensed coaches can be assigned.

Pattern: ^[A-Z]{2}$

Example:

"NY"

timezone

string

default:America/New_York

IANA time zone. Log dates and reminders follow it.

Example:

"America/New_York"

language

string

default:en

BCP 47 language tag.

Example:

"en"

units

enum<string>

Display preference only. The API always takes and returns metric values.

Available options:

metric,

imperial

Example:

"imperial"

conditions

string[]

Condition codes the brand's rule matrix keys on, for example type_2_diabetes.

Pattern: ^[a-z][a-z0-9_]*$

Example:

["prediabetes"]

health_profile

object

What plans and the AI Coach are built around. Every field is optional. In a PATCH, send only what changes; null clears a value and [] clears a list.

Show child attributes

Response

The enrollment's status after the change.

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

Update the patient's details

Authorizations

Path Parameters

Body

Response