Cancel Appointment¶

Cancels an appointment and returns the updated record.

Endpoint¶

POST /v2/appointments/{appointment_id}/cancel

Path Parameters¶

Parameter	Type	Required	Description
`appointment_id`	string	Yes

Request Body¶

Parameter	Type	Required	Description
`reason_key`	string	Yes	A `reason_key` from Appointment Cancellation Reasons.
`reason_label`	string	No	Human-readable label for the reason. Defaults to `reason_key` when omitted.
`comment`	string	No

Request¶

curl --location '{base_url}/v2/appointments/appointment_id/cancel' \
  --header 'Authorization: Bearer JWT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "reason_key": "Transportation",
  "reason_label": "Patient request",
  "comment": null
}'

Response¶

Success Response¶

Code: 200 OK

{
  "id": "418907",
  "patient_id": "63120",
  "provider_id": "2094",
  "clinic_id": "5831",
  "spry_case_id": "SPRY-63120-2",
  "referring_therapist_id": "2187",
  "appointment_type_id": "318",
  "start_time": "2026-09-14T16:00:00Z",
  "end_time": "2026-09-14T17:00:00Z",
  "status": "CONFIRMED",
  "payment_mode": "INSURANCE_PAY",
  "telehealth_url": null,
  "notes": null,
  "source": "EXTERNAL_API",
  "recurrence": {
    "frequency": "WEEKLY",
    "interval": 1,
    "days_of_week": [
      "MONDAY",
      "TUESDAY"
    ],
    "end_date": "2026-12-31",
    "series_id": null
  },
  "cancellation": {
    "reason_key": "Transportation",
    "reason_code": "TRANSPORTATION",
    "comment": null,
    "cancelled_at": null,
    "fee": null
  },
  "checked_in_at": null,
  "checked_out_at": null,
  "patient": {
    "patient_id": "63120",
    "first_name": "Morgan",
    "middle_name": null,
    "last_name": "Delgado",
    "suffix": null,
    "date_of_birth": "1991-07-23",
    "gender": "MALE",
    "email": "m.delgado@example.com",
    "mobile": "+1-555-0155",
    "address": {
      "line1": "482 Willow Creek Rd",
      "line2": null,
      "city": "Fairview",
      "state": "OR",
      "postal_code": "97024",
      "country": "US"
    },
    "preferred_language": "en",
    "status": "CREATED",
    "organisation_id": "7412",
    "clinic_ids": [
      "5831"
    ],
    "provider_ids": [
      "2094"
    ],
    "referring_therapist_id": "2187",
    "secondary_contact": null,
    "photo_url": null,
    "height": null,
    "weight": null,
    "tags": [
      "HIGH_RISK",
      "SPANISH_SPEAKING"
    ],
    "created_at": "2026-08-27T14:30:00Z",
    "updated_at": "2026-08-27T14:30:00Z"
  },
  "provider": {
    "id": "418907",
    "onboarding_provider_id": "d27a6b10-9f34-4e82-b5c1-7a03e8946fd2",
    "user_id": "2094",
    "first_name": "Morgan",
    "middle_name": null,
    "last_name": "Delgado",
    "email": "m.delgado@example.com",
    "mobile": "+1-555-0155",
    "npi": "1740398215",
    "license": "PT-30914",
    "speciality": "PHYSICAL_THERAPY",
    "sub_specialities": [
      "PELVIC_FLOOR"
    ],
    "qualifications": [
      "DPT"
    ],
    "photo_url": null,
    "about": null,
    "signature_url": null,
    "status": "CONFIRMED",
    "online_booking_enabled": true,
    "clinics": [
      {
        "clinic_id": "5831",
        "onboarding_clinic_id": "b41f7c92-5e08-4a13-8d6f-2c9147ab3e5d",
        "status": "CONFIRMED",
        "online_booking_enabled": true,
        "hours": [
          {
            "days_of_week": [
              "MONDAY",
              "TUESDAY"
            ],
            "start_time": "08:00",
            "end_time": "17:00"
          }
        ]
      }
    ],
    "home_health": {
      "enabled": true,
      "state_code": "OR",
      "address": {
        "line1": "482 Willow Creek Rd",
        "line2": null,
        "city": "Fairview",
        "state": "OR",
        "postal_code": "97024",
        "country": "US"
      },
      "location": {
        "lat": 45.5231,
        "lng": -122.6765
      },
      "transport_mode": "CAR",
      "max_drive_seconds": 1800,
      "max_visits_per_week": 12,
      "max_allowed_visits_per_slot": 1,
      "target_hours_weekly": 18,
      "online_booking": true,
      "pet_comfort": true,
      "stair_comfort": true,
      "accepting_new_patients": true,
      "schedules": [
        {
          "effective_start_date": "2026-09-01",
          "effective_end_date": null,
          "entries": [
            {
              "days_of_week": [
                "MONDAY",
                "TUESDAY"
              ],
              "start_time": "08:00",
              "end_time": "17:00",
              "address": {
                "line1": "482 Willow Creek Rd",
                "line2": null,
                "city": "Fairview",
                "state": "OR",
                "postal_code": "97024",
                "country": "US"
              },
              "location": {
                "lat": 45.5231,
                "lng": -122.6765
              }
            }
          ]
        }
      ],
      "scheduling_overrides": {
        "2026-09-17": {
          "ranges": []
        },
        "2026-09-20": {
          "ranges": [
            {
              "start_time": "10:00",
              "end_time": "12:00"
            }
          ]
        }
      }
    },
    "external_reference_id": "provider-4471",
    "external_reference_metadata": {
      "source_system": "example-hr",
      "employee_id": "10442"
    },
    "patient_scoped": false,
    "name_prefix": null,
    "credential": "DPT",
    "dob": "1991-07-23",
    "gender": "MALE",
    "ptan": null,
    "sole_proprietor": false,
    "taxonomies": [
      {
        "code": "97110",
        "desc": null,
        "group_code": null,
        "group_desc": null,
        "license": "PT-30914",
        "primary": null,
        "specialization": "PHYSICAL_THERAPY",
        "state": "OR"
      }
    ],
    "primary_taxonomy_code": null,
    "online_booking": [
      {
        "clinic_id": "5831",
        "enabled": true
      }
    ],
    "schedule": [
      {
        "clinic_id": "5831",
        "timings": [
          {
            "days_of_week": [
              "MONDAY",
              "TUESDAY"
            ],
            "start_time": "08:00",
            "end_time": "17:00"
          }
        ]
      }
    ],
    "billing_profile_ids": [],
    "billing_profiles": [
      {
        "billing_profile_id": "b7e4c1a2-6f3d-4e9b-9a51-2c8d0f7e3a14",
        "display_name": null,
        "effective_from": "2026-01-01",
        "effective_to": null
      }
    ],
    "direct_access_permitted": null,
    "referral_code": null,
    "access_revoked": false,
    "created_at": "2026-08-27T14:30:00Z",
    "updated_at": "2026-08-27T14:30:00Z"
  },
  "clinic": {
    "id": "418907",
    "onboarding_clinic_id": "b41f7c92-5e08-4a13-8d6f-2c9147ab3e5d",
    "organisation_id": "7412",
    "name": "Example Therapy \u2014 Riverside",
    "email": "m.delgado@example.com",
    "phone": "+1-555-0143",
    "fax": null,
    "address": {
      "line1": "482 Willow Creek Rd",
      "line2": null,
      "city": "Fairview",
      "state": "OR",
      "postal_code": "97024",
      "country": "US"
    },
    "timezone": "America/Los_Angeles",
    "npi": "1740398215",
    "logo_url": "https://assets.example.com/logo.png",
    "about": null,
    "specialities": [
      "PT",
      "OT"
    ],
    "hours": [
      {
        "days_of_week": [
          "MONDAY",
          "TUESDAY"
        ],
        "start_time": "08:00",
        "end_time": "17:00"
      }
    ],
    "online_booking_enabled": true,
    "max_visits_per_slot": 3,
    "status": "ONBOARDING",
    "created_at": "2026-08-27T14:30:00Z",
    "updated_at": "2026-08-27T14:30:00Z"
  },
  "coverage": {
    "primary": {
      "id": "418907",
      "patient_id": "63120",
      "rank": "PRIMARY",
      "payer": {
        "id": "418907",
        "name": "Example Therapy \u2014 Riverside"
      },
      "member_id": "K631204418",
      "group_number": "GRP-4471",
      "group_name": null,
      "plan": {
        "name": "Example Therapy \u2014 Riverside",
        "type": null
      },
      "coverage_type": "COMMERCIAL",
      "subscriber": {
        "relationship": "SELF",
        "first_name": "Morgan",
        "last_name": "Delgado",
        "date_of_birth": "1991-07-23"
      },
      "effective_from": "2026-01-01",
      "effective_to": null,
      "status": "CONFIRMED",
      "created_at": "2026-08-27T14:30:00Z",
      "updated_at": "2026-08-27T14:30:00Z"
    },
    "secondary": {
      "id": "418907",
      "patient_id": "63120",
      "rank": "PRIMARY",
      "payer": {
        "id": "418907",
        "name": "Example Therapy \u2014 Riverside"
      },
      "member_id": "K631204418",
      "group_number": "GRP-4471",
      "group_name": null,
      "plan": {
        "name": "Example Therapy \u2014 Riverside",
        "type": null
      },
      "coverage_type": "COMMERCIAL",
      "subscriber": {
        "relationship": "SELF",
        "first_name": "Morgan",
        "last_name": "Delgado",
        "date_of_birth": "1991-07-23"
      },
      "effective_from": "2026-01-01",
      "effective_to": null,
      "status": "CONFIRMED",
      "created_at": "2026-08-27T14:30:00Z",
      "updated_at": "2026-08-27T14:30:00Z"
    }
  },
  "created_at": "2026-08-27T14:30:00Z",
  "updated_at": "2026-08-27T14:30:00Z"
}

Response Fields¶

Field	Type	Description
`id`	string	The appointment id.
`patient_id`	string or null	The patient. Correlate on this — it's a stable id, and there's no external-reference field.
`provider_id`	string or null	The treating provider.
`clinic_id`	string or null	The clinic this record belongs to.
`spry_case_id`	string or null	The case's business key.
`referring_therapist_id`	string or null	The provider who referred the patient, copied onto the visit when it was booked. `null` when the patient wasn't referred, and for visits created through `POST /v2/appointments`, which don't carry a referrer yet. Always present: if it can't be determined, the request fails instead of answering without it — `503` with a `Retry-After` header when temporary (retry the same request), `502` when it isn't. For a change to an appointment (update, cancel, check-in, check-out), that `503` or `502` comes before anything is changed.
`appointment_type_id`	string or null	The appointment type, from List Appointment Types. A single id, not a list.
`start_time`	string (date-time)	When the visit starts, as an ISO-8601 UTC instant.
`end_time`	string (date-time) or null	When the visit ends, as an ISO-8601 UTC instant. Computed from the appointment type's duration when omitted on create.
`status`	string or null	One of `CONFIRMED`, `CANCELLED`, `SOAP_COMPLETED`, `PI_FILLED`, `PATIENT_CHECKIN`, `PATIENT_CHECKOUT`, `IN_PROCESS`.
`payment_mode`	string or null	How the visit is paid for. Required on create; omitting it fails the booking with an unhelpful error. One of `CASH`, `CARD`, `UPI`, `WALLET`, `SELF_PAY`, `INSURANCE_PAY`, `BILLING`.
`telehealth_url`	string or null	Video visit link, when the appointment is virtual.
`notes`	string or null
`source`	string or null	Where the record originated.
`recurrence`	object or null	Recurrence rule. `null` for a one-off. See Recurrence.
`cancellation`	object or null	Cancellation details. `null` unless the appointment was cancelled. See Cancellation.
`checked_in_at`	string (date-time) or null	Set by Check In.
`checked_out_at`	string (date-time) or null	Set by Check Out.
`patient`	object or null	See Patient.
`provider`	object or null	See Provider.
`clinic`	object or null	See Clinic.
`coverage`	object	See Coverage.
`created_at`	string (date-time) or null
`updated_at`	string (date-time) or null

Recurrence¶

Field	Type	Description
`frequency`	string	How often the pattern repeats.
`interval`	integer	Repeat every N periods of `frequency`.
`days_of_week`	array of string
`end_date`	string (date)	`YYYY-MM-DD`.
`series_id`	string or null	Groups the appointments generated from one recurring booking.

Cancellation¶

Field	Type	Description
`reason_key`	string or null	Cancellation reason. Free text, not an enum.
`reason_code`	string or null	Machine-readable cancellation reason code, matching a `reason_key` from Appointment Cancellation Reasons when the appointment was cancelled with one of those.
`comment`	string or null
`cancelled_at`	string (date-time) or null
`fee`	number or null	Cancellation fee applied, when any.

Patient¶

Field	Type	Description
`patient_id`	string	The patient. Correlate on this — it's a stable id, and there's no external-reference field.
`first_name`	string
`middle_name`	string or null
`last_name`	string
`suffix`	string or null
`date_of_birth`	string (date) or null	`YYYY-MM-DD`.
`gender`	string or null	Administrative gender, matching FHIR `Patient.gender` — used for demographics and claims, not a clinical assertion. One of `MALE`, `FEMALE`, `OTHER`, `UNKNOWN`.
`email`	string or null
`mobile`	string or null
`address`	object or null	See Address.
`preferred_language`	string or null	ISO 639-1 language code — one of `en`, `es`, `fr`, `de`, `it`, `pt`, `ru`, `ar`, `hy`, `cy`, `zh`, `zh-Hans`, `zh-Hant`, `ja`, `ko`, `th`, `jv`, `hi`, `bn`, `gu`, `kn`, `ml`, `mr`, `or`, `pa`, `ta`, `te`, `ur`.
`status`	string	One of `CREATED`, `ACTIVE`, `INACTIVE`, `DISCHARGED`.
`organisation_id`	string or null	The organisation this record belongs to. Derived from the access token on writes and never trusted from the body.
`clinic_ids`	array of string	Clinics this record is associated with.
`provider_ids`	array of string	Providers associated with this record.
`referring_therapist_id`	string or null	The provider who referred the patient. `null` for none. Read-only.
`secondary_contact`	string or null
`photo_url`	string or null	A fetchable URL. It may be a time-limited signed URL, so fetch it rather than storing it.
`height`	string or null
`weight`	string or null
`tags`	array of string	Labels applied to the patient. `[]` when the patient has none — and also when the tags lookup fails, since a tags outage does not fail the whole patient read. Always `[]` on List Patients, which skips the per-patient tags lookup; read a patient by id for its tags. Read-only for now.
`created_at`	string (date-time) or null
`updated_at`	string (date-time) or null

Address¶

Field	Type	Description
`line1`	string or null
`line2`	string or null
`city`	string or null
`state`	string or null
`postal_code`	string or null
`country`	string or null

Provider¶

Field	Type	Description
`id`	string or null	The appointment id.
`onboarding_provider_id`	string or null	The provider's onboarding-record UUID.
`user_id`	string or null	The provider's user id. Same value as the provider `id`; both are returned rather than leaving that implicit.
`first_name`	string or null
`middle_name`	string or null
`last_name`	string or null
`email`	string or null
`mobile`	string or null
`npi`	string or null
`license`	string or null
`speciality`	string or null	The record's primary speciality.
`sub_specialities`	array of string	The provider's sub-specialities, as codes from your organisation's own list, which Spry configures per organisation. A code that isn't on that list is refused, and so is the same code twice. Replaces the whole list on write; `null` clears it.
`qualifications`	array of string
`photo_url`	string or null	A fetchable URL. It may be a time-limited signed URL, so fetch it rather than storing it.
`about`	string or null
`signature_url`	string or null	A fetchable URL. Treat it as time-limited and fetch it rather than storing it. In environments where signing is unavailable the raw stored value is returned, which isn't fetchable.
`status`	string or null
`online_booking_enabled`	boolean or null	Whether this record is bookable through online booking.
`clinics`	array of object	See Clinics.
`home_health`	object or null	Home-visit settings for this provider. `null` when the provider has no home-visit configuration. See Home Health.
`external_reference_id`	string or null	Your own identifier for this provider. Stored only — it has no effect on Spry behaviour.
`external_reference_metadata`	object or null	Your own reference data for this provider, as a JSON object. Stored only — Spry never reads it, and its keys come back exactly as sent. It must not contain patient data. Send ids as strings: integers above 2^53 lose precision. At most 16 KB serialized and 5 levels deep; keys may not contain `.` or start with `$`. On update, `{"key": null}` inside it removes that key and `null` clears the whole object.
`patient_scoped`	boolean	When true, restricts the provider to only their own assigned patients (HIPAA minimum-necessary). When false (default), the provider can access all patients in the organisation.
`name_prefix`	string or null
`credential`	string or null
`dob`	string (date) or null	`YYYY-MM-DD`.
`gender`	string or null	Administrative gender, matching FHIR `Patient.gender` — used for demographics and claims, not a clinical assertion.
`ptan`	string or null	Provider Transaction Access Number.
`sole_proprietor`	boolean or null
`taxonomies`	array of object	See Taxonomies.
`primary_taxonomy_code`	string or null	NUCC provider taxonomy code.
`online_booking`	array of object	Whether this record is bookable through online booking. See Online Booking.
`schedule`	array of object	See Schedule.
`billing_profile_ids`	array of string	Billing profiles attached to this provider. On write it changes membership only and keeps the affiliation dates — prefer `billing_profiles`.
`billing_profiles`	array of object	The profiles in `billing_profile_ids`, in the same order, each with this provider's affiliation window. On write it replaces the whole list: the provider is attached to exactly the profiles listed, and a date left out or `null` is cleared. Sent together with `billing_profile_ids`, both must name the same profiles (`422` otherwise). See Billing Profiles.
`direct_access_permitted`	boolean or null
`referral_code`	string or null
`access_revoked`	boolean	Whether the provider's onboarding access has been revoked.
`created_at`	string (date-time) or null
`updated_at`	string (date-time) or null

Clinics¶

Field	Type	Description
`clinic_id`	string or null	The clinic this record belongs to.
`onboarding_clinic_id`	string or null	The clinic's onboarding-record UUID. Always present for clinics created through onboarding, and the only way to address one before it's published.
`status`	string or null
`online_booking_enabled`	boolean or null	Whether this record is bookable through online booking.
`hours`	array of object	Working hours, as one entry per distinct daily pattern. See Hours.

Hours¶

Field	Type	Description
`days_of_week`	array of string	Any of `MONDAY`, `TUESDAY`, `WEDNESDAY`, `THURSDAY`, `FRIDAY`, `SATURDAY`, `SUNDAY`.
`start_time`	string	When the visit starts, as an ISO-8601 UTC instant. 24-hour `HH:MM`.
`end_time`	string	When the visit ends, as an ISO-8601 UTC instant. Computed from the appointment type's duration when omitted on create. 24-hour `HH:MM`.

Home Health¶

Field	Type	Description
`enabled`	boolean
`state_code`	string or null	Two-letter state the provider is licensed to visit in.
`address`	object or null	See Address.
`location`	object or null	Geographic point the visit window is anchored to. See Location.
`transport_mode`	string or null	How the provider travels between visits. One of `CAR`, `BIKE`, `WALK`, `TRANSIT`.
`max_drive_seconds`	integer or null	Longest drive the provider will accept between consecutive visits, in seconds: `1500` (25 minutes) to `14400` (4 hours). Defaults to `1800`.
`max_visits_per_week`	integer or null	Cap on home visits per week, `1` to `100`. Defaults to `2`.
`max_allowed_visits_per_slot`	integer or null	Home visits per schedule slot. Always `1`; ignored on write.
`target_hours_weekly`	integer or null	Target hours of home visits per week, derived from `max_visits_per_week`: ×1.4 under 10 visits, ×1.5 for 10–19, ×1.6 from 20, rounded up to a whole hour. Ignored on write.
`online_booking`	boolean or null	Whether this record is bookable through online booking.
`pet_comfort`	boolean	Whether the provider will visit homes with pets. Always `true`; ignored on write.
`stair_comfort`	boolean	Whether the provider will visit homes requiring stairs. Always `true`; ignored on write.
`accepting_new_patients`	boolean or null	Whether this provider is accepting new home-health patients. Defaults to `true`.
`schedules`	array of object	Independent home-visit availability periods, each with its own weekly `entries[]`. Periods must not overlap, and at most one may be open-ended. See Schedules.
`scheduling_overrides`	object	Per-date exceptions to the weekly schedule, keyed `YYYY-MM-DD`. A key's presence is what marks a day off from no override — empty `ranges` (absent entirely on read) means no visits that day, and a populated `ranges[]`, each a `{start_time, end_time}` window with an optional `address`/`location` to anchor it away from the provider's home base, replaces the weekly pattern for that date. Every date must fall inside one of `schedules[]`'s periods, and past dates are rejected. On write, an explicit `null` clears a key and restores the weekly pattern; an omitted key is left alone.

Location¶

Field	Type	Description
`lat`	number	Latitude, decimal degrees.
`lng`	number	Longitude, decimal degrees.

Schedules¶

Field	Type	Description
`effective_start_date`	string (date)	When this period takes effect. `YYYY-MM-DD`.
`effective_end_date`	string (date) or null	When this period stops applying. `null` for open-ended — periods must not overlap, and at most one may be open-ended. `YYYY-MM-DD`.
`entries`	array of object	See Entries.

Entries¶

Field	Type	Description
`days_of_week`	array of string	Any of `MONDAY`, `TUESDAY`, `WEDNESDAY`, `THURSDAY`, `FRIDAY`, `SATURDAY`, `SUNDAY`.
`start_time`	string	When the visit starts, as an ISO-8601 UTC instant. 24-hour `HH:MM`.
`end_time`	string	When the visit ends, as an ISO-8601 UTC instant. Computed from the appointment type's duration when omitted on create. 24-hour `HH:MM`.
`address`	object	See Address.
`location`	object	Geographic point the visit window is anchored to. See Location.

Taxonomies¶

Field	Type	Description
`code`	string
`desc`	string or null
`group_code`	string or null
`group_desc`	string or null
`license`	string or null
`primary`	boolean or null
`specialization`	string or null
`state`	string or null

Online Booking¶

Field	Type	Description
`clinic_id`	string	The clinic this record belongs to.
`enabled`	boolean

Schedule¶

Field	Type	Description
`clinic_id`	string	The clinic this record belongs to.
`timings`	array of object	See Timings.

Timings¶

Field	Type	Description
`days_of_week`	array of string	Any of `MONDAY`, `TUESDAY`, `WEDNESDAY`, `THURSDAY`, `FRIDAY`, `SATURDAY`, `SUNDAY`.
`start_time`	string	When the visit starts, as an ISO-8601 UTC instant. 24-hour `HH:MM`.
`end_time`	string	When the visit ends, as an ISO-8601 UTC instant. Computed from the appointment type's duration when omitted on create. 24-hour `HH:MM`.

Billing Profiles¶

Field	Type	Description
`billing_profile_id`	string	The billing profile this record belongs to.
`display_name`	string or null	Read-only; null when the id matches no profile.
`effective_from`	string (date) or null	`YYYY-MM-DD`.
`effective_to`	string (date) or null	`YYYY-MM-DD`.

Clinic¶

Field	Type	Description
`id`	string or null	The appointment id.
`onboarding_clinic_id`	string or null	The clinic's onboarding-record UUID. Always present for clinics created through onboarding, and the only way to address one before it's published.
`organisation_id`	string or null	The organisation this record belongs to. Derived from the access token on writes and never trusted from the body.
`name`	string
`email`	string or null
`phone`	string or null
`fax`	string or null
`address`	object or null	See Address.
`timezone`	string or null	IANA timezone name.
`npi`	string or null
`logo_url`	string or null
`about`	string or null
`specialities`	array of string
`hours`	array of object	Working hours, as one entry per distinct daily pattern. See Hours.
`online_booking_enabled`	boolean	Whether this record is bookable through online booking.
`max_visits_per_slot`	integer or null
`status`	string	One of `ONBOARDING`, `ACTIVE`, `INACTIVE`.
`created_at`	string (date-time) or null
`updated_at`	string (date-time) or null

Coverage¶

Field	Type	Description
`primary`	object or null	See Primary.
`secondary`	object or null	See Secondary.

Primary¶

Field	Type	Description
`id`	string	The appointment id.
`patient_id`	string	The patient. Correlate on this — it's a stable id, and there's no external-reference field.
`rank`	string or null	The patient's general coordination-of-benefits order. Separate from a case's coverage pointers, which say which plans bill that episode — they legitimately differ. `null` when the card is unallocated. One of `PRIMARY`, `SECONDARY`, `TERTIARY`.
`payer`	object	The insurance payer, as a registry reference. See Payer.
`member_id`	string or null	The member's id on the plan.
`group_number`	string or null
`group_name`	string or null
`plan`	object	The plan on this coverage. See Plan.
`coverage_type`	string or null	How this plan is billed. One of `COMMERCIAL`, `MEDICARE`, `MEDICAID`, `WORKERS_COMP`, `MVC`, `SELF_PAY`.
`subscriber`	object or null	The plan's subscriber, when it is not the patient. See Subscriber.
`effective_from`	string (date) or null	`YYYY-MM-DD`.
`effective_to`	string (date) or null	`YYYY-MM-DD`.
`status`	string
`created_at`	string (date-time) or null
`updated_at`	string (date-time) or null

Payer¶

Field	Type	Description
`id`	string or null	The appointment id.
`name`	string or null

Plan¶

Field	Type	Description
`name`	string or null
`type`	string or null

Subscriber¶

Field	Type	Description
`relationship`	string	The subscriber's relationship to the patient. One of `SELF`, `SPOUSE`, `CHILD`, `OTHER`.
`first_name`	string or null
`last_name`	string or null
`date_of_birth`	string (date) or null	`YYYY-MM-DD`.

Secondary¶

Field	Type	Description
`id`	string	The appointment id.
`patient_id`	string	The patient. Correlate on this — it's a stable id, and there's no external-reference field.
`rank`	string or null	The patient's general coordination-of-benefits order. Separate from a case's coverage pointers, which say which plans bill that episode — they legitimately differ. `null` when the card is unallocated. One of `PRIMARY`, `SECONDARY`, `TERTIARY`.
`payer`	object	The insurance payer, as a registry reference. See Payer.
`member_id`	string or null	The member's id on the plan.
`group_number`	string or null
`group_name`	string or null
`plan`	object	The plan on this coverage. See Plan.
`coverage_type`	string or null	How this plan is billed. One of `COMMERCIAL`, `MEDICARE`, `MEDICAID`, `WORKERS_COMP`, `MVC`, `SELF_PAY`.
`subscriber`	object or null	The plan's subscriber, when it is not the patient. See Subscriber.
`effective_from`	string (date) or null	`YYYY-MM-DD`.
`effective_to`	string (date) or null	`YYYY-MM-DD`.
`status`	string
`created_at`	string (date-time) or null
`updated_at`	string (date-time) or null

Error Response¶

Code: 400 Bad Request

{
  "code": "bad_request",
  "message": "Validation failed",
  "errors": [
    {
      "field": "patient_id",
      "message": "must be a string"
    }
  ]
}

Every error has the same shape — a machine-readable code, a message, and an errors[] array that's empty when there's nothing field-specific to report. The HTTP status is authoritative.

Status	`code`	Meaning
`400 Bad Request`	`bad_request`	The request body or parameters failed validation. `errors[]` names the offending fields.
`401 Unauthorized`	`unauthorized`	The access token is missing, malformed or expired.
`403 Forbidden`	`forbidden`	The request references a resource outside the token's organisation or clinic scope.
`404 Not Found`	`not_found`	No such resource, or it's outside your scope.
`429 Too Many Requests`	`rate_limited`	Rate limit exceeded. Back off and retry.
`500 Internal Server Error`	`internal_error`	Unexpected server error.
`502 Bad Gateway`	`upstream_error`	Upstream service failed or timed out.
`503 Service Unavailable`	`service_unavailable`	Temporarily unavailable — retry the same request after the number of seconds in the `Retry-After` header. On a change to a resource, nothing was changed.