Skip to main content

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 the shop_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.
Required permission: patient:write
string
required
UID of the shop the customer belongs to
string
required
The shop’s identifier for the customer
string
Optional patient email stored on the shop-patient mapping and used for patient lookup/search.
array
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.
string
required
The email address to search for
Required permission: patient:read

Example Request

Response

Error Responses

Get Patient Profile

Retrieve a patient profile by UID.
string
required
The patient UID
Required permission: 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.
string
required
The patient UID
string
required
The intent identifier
Required permission: patient:read

Example Request

Response

Return Code Values

Delete Patient Profile Field

Delete a patient’s value for a single profile field.
string
required
The patient UID
string
required
Key of the profile field to delete the patient’s value for
string
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.
The field key is the same value you send in 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
This is a hard delete. The field value is removed from the patient’s profile, not archived or soft-deleted. An internal audit log entry recording the deletion (naming the API key that performed it) is written as part of the same call — afterwards, that log entry is the only remaining record that the value ever existed.

Example Request

Response (200 OK)

Error Responses

List Organisation Tags

List the categorization tags of the authenticated organisation, ordered by identifier. Use a returned uid or identifier when attaching a tag to a patient. Intent tags are not included.
integer
default:"0"
Page number, starting at 0
integer
default:"50"
Tags per page. Maximum 200
Required permission: patient_tag:read

Example Request

Response

List Patient Tags

List the categorization tags attached to one patient, ordered by identifier. This is the same set as the tags array on the patient response. Intent tags are omitted.
string
required
The patient UID
Required permission: patient_tag:read

Example Request

Response

Error Responses

Attach a Patient Tag

Attach a categorization tag to a patient. Send exactly one of tag_uid or identifier.
  • tag_uid attaches a tag that already exists in this organisation.
  • identifier attaches the organisation’s tag with that identifier. If none exists, a categorization tag is created and attached. display_name and color_hex are used only in that create case. color_hex defaults to #10B981. display_name defaults to the identifier.
Intent tags are rejected. A tag that belongs to another organisation is not found. Attaching a tag that is already on the patient returns 409.
string
required
The patient UID
string
UID of an existing categorization tag in this organisation. Mutually exclusive with identifier.
string
Identifier of an existing categorization tag, or a new identifier to create. Mutually exclusive with tag_uid.
string
Label stored only when identifier is created
string
#RRGGBB color stored only when identifier is created. Defaults to #10B981
Required permission: 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.
string
required
The patient UID
string
required
UID of the categorization tag to detach
Required permission: patient_tag:write

Example Request

Response (200 OK)

Error Responses