Patients
Search for patients by email address, view patient profiles, and check patient intent status. Patient responses include the organisation’s categorization tags for that patient.Create or Resolve Patient
Create a patient profile for a shop customer, or return the existing profile if theshop_uid and shop_customer_id pair already exists. This is step 1 for Patient Pass issuance (POST /wallet-passes needs that shop-customer link) and the supported create flow for Scheduling.
patient:write
Optional patient profile fields to set for the shop customer. Each entry is
{ "field": "<field_key>", "value": <value>, "source": "shop" | "questionnaire" | "user" }.
source defaults to shop and must match the field’s configured source in
Settings → Profile Fields. A mismatch or unknown field key returns 404.
Patient Profile Fields explains
each source. A value you set for a shop field is replaced the next time the customer
changes in Shopify, if the Shopify customer has a value for that field.Search Patient by Email
Find a patient by their email address. Returns the most recently created patient whose shop-patient email or order email matches the given email.patient:read
Example Request
Response
Error Responses
Get Patient Profile
Retrieve a patient profile by UID.patient:read
Example Request
Response
tags lists categorization tags only. Each object has uid, identifier, display_name, and color_hex. Intent tags are omitted. A tag is free text belonging to your organisation and is returned only to that organisation. The text can relate to health. Reading the patient requires patient:read. The tags array is part of that response.
Check Patient Intent
Check the intent return code for a patient. Returns a code indicating when the last signed submission for this intent was made.patient:read
Example Request
Response
Return Code Values
Delete Patient Profile Field
Delete a patient’s value for a single profile field.Source of the field (
shop, questionnaire, or user). Must match the profile field’s configured source and the source used when writing the value via Create or Resolve Patient. Defaults to shop.fields[].field when setting a value via Create or Resolve Patient — for example first_name. Pass the same source you used when writing the value. Deleting a value therefore uses exactly the identifier you used to set it; no separate lookup is needed.
Required permission: patient_profile_field:delete
Example Request
Response (200 OK)
Error Responses
List Organisation Tags
List the categorization tags of the authenticated organisation, ordered byidentifier. Use a returned uid or identifier when attaching a tag to a patient. Intent tags are not included.
patient_tag:read
Example Request
Response
List Patient Tags
List the categorization tags attached to one patient, ordered byidentifier. This is the same set as the tags array on the patient response. Intent tags are omitted.
patient_tag:read
Example Request
Response
Error Responses
Attach a Patient Tag
Attach a categorization tag to a patient. Send exactly one oftag_uid or identifier.
tag_uidattaches a tag that already exists in this organisation.identifierattaches the organisation’s tag with that identifier. If none exists, a categorization tag is created and attached.display_nameandcolor_hexare used only in that create case.color_hexdefaults to#10B981.display_namedefaults to the identifier.
409.
UID of an existing categorization tag in this organisation. Mutually exclusive with
identifier.Identifier of an existing categorization tag, or a new identifier to create. Mutually exclusive with
tag_uid.patient_tag:write
Example Request
Response (201 Created)
Error Responses
Detach a Patient Tag
Remove one categorization tag from a patient. The tag itself remains available to the organisation, and mappings of the same tag on other records are left in place. Intent tags are rejected.patient_tag:write