Patients

Each Appendix account holder can manage one or more people— themselves, their spouse, their kids. Encounters are bound to a specific person via patient_id; an agent uses these endpoints to look up “which person on the account is this for” and to add new family members.

All endpoints require authentication (Clerk JWT or personal API key) and scope to the caller’s own people. Foreign patient IDs return 404.

List people on your account

GET/api/v1/patients

Returns every active patient owned by the authenticated user. The id field is the value to pass as patient_id on POST /api/v1/agent/query.

200 OK

[
  {
    "id": "patient-uuid-1",
    "ownerId": "user-uuid",
    "relationship": "self",
    "firstName": "Alex",
    "lastName": "Doe",
    "dateOfBirth": "1990-04-12",
    "sex": "M",
    "stateOfResidence": "CA",
    "phoneNumber": "+14155550100",
    "consentedToTelehealth": true,
    "identityVerification": { "status": "inherits_owner" },
    "createdAt": "2026-01-10T18:00:00Z"
  },
  {
    "id": "patient-uuid-2",
    "relationship": "spouse",
    "firstName": "Jamie",
    "lastName": "Doe",
    "dateOfBirth": "1991-08-04",
    "sex": "F",
    "identityVerification": { "status": "verified" },
    "consentedToTelehealth": true
  }
]

The relationship field is one of self, spouse, child, parent, guardian, dependent, other. Agents use it to map a phrase like “this is for my wife” onto the right person.

Get patient

GET/api/v1/patients/{id}

Returns the same shape as a list entry, plus any clinician-confirmed allergy and medication history. Use this when you already have an id from a list call and want the freshest record.

Add a person

POST/api/v1/patients

Adds a new patient under the caller’s account. New patients start unverified; before they can have an encounter auto-submitted, they need telehealth consent (PATCH /patients/{id} with consentedToTelehealth: true) and identity verification (POST /patients/{id}/identity-session starts the Stripe Identity flow). Self-patients and minors inherit the account holder’s identity verification automatically.

Parameter	Type	Required	Description
`relationship`	string	Required	One of self, spouse, child, parent, guardian, dependent, other.
`firstName`	string	Required	Legal first name.
`lastName`	string	Required	Legal last name.
`dateOfBirth`	string	Required	YYYY-MM-DD.
`sex`	string	Required	Biological sex (M / F).
`stateOfResidence`	string	Required	Two-letter US state code. Determines which physicians can prescribe.
`phoneNumber`	string	Required	E.164 format (+14155550100). 10-digit US numbers are auto-prefixed with +1.

curl

curl -X POST https://api.appendix.com/api/v1/patients \
  -H "Authorization: Bearer ak_..." \
  -H "Content-Type: application/json" \
  -d '{
    "relationship": "spouse",
    "firstName": "Jamie",
    "lastName": "Doe",
    "dateOfBirth": "1991-08-04",
    "sex": "F",
    "stateOfResidence": "CA",
    "phoneNumber": "+14155550101"
  }'

Update patient

PATCH/api/v1/patients/{id}

Edits a patient’s demographics. Once identity verification is complete, every field except phoneNumber is locked — name, DOB, sex, state, and consent become immutable. Use this endpoint to record telehealth consent (consentedToTelehealth: true) before submitting on the patient’s behalf.

Parameter	Type	Required	Description
`firstName`	string	Optional	Pre-IV only.
`lastName`	string	Optional	Pre-IV only.
`dateOfBirth`	string	Optional	Pre-IV only.
`sex`	string	Optional	Pre-IV only.
`stateOfResidence`	string	Optional	Pre-IV only.
`phoneNumber`	string	Optional	Editable any time. E.164 format.
`consentedToTelehealth`	boolean	Optional	Set to true to record consent. Cannot be un-set via PATCH.

Remove patient

DELETE/api/v1/patients/{id}

Archives a non-self patient. If a prescription has been written for this patient in the current billing cycle, the seat keeps billing until the period end and the patient retains access until then; otherwise the seat is released immediately with a prorated credit. Self-patients cannot be deleted — cancel the subscription instead.