Skip to main content
Patients are the people your scribe sessions are about. Create a patient once and reuse its stable public id (sp_...) across consultations, instead of re-sending identity fields every time. The identity fields (name, idCountry, idType, idValue) are the same ones used by set-consultation-context and follow the same validation rules — see Accepted documents by country.
Patients are tenant-scoped by your API key’s role: a doctor key sees only its own patients; an institutional key sees every patient within its institution. You never need to pass an account or institution id — scoping is enforced server-side.

​
Creating a patient

POST /v1/patients requires name, idCountry, idType, and idValue. The idType must be valid for the given idCountry (e.g. CC with idCountry: BR returns 400).
Response:
Save the id (sp_...) — it’s stable and reusable. Creating a patient with an identity document that already exists returns the existing patient rather than a duplicate.

​
Listing patients

GET /v1/patients returns the patients visible to your key, most recent first. Paginate with page (1-based) and limit (1–50, default 20).
Response:
total and totalPages are only computed on the first page — they are null on later pages to avoid a full scan on every page click. Use hasMore to paginate reliably; it is accurate on every page.

​
Retrieving a patient

GET /v1/patients/{patient_id} looks up a single patient by its public id (sp_...). Returns 404 if no patient with that id is visible to your key.
Response:
idCountry, idType, and idValue may be null for patients created outside this API that carry no identification.