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).
internalCode is optional. It is your own identifier for the patient, unique within your institution. Send it on create, then fetch the patient or list its sessions by that code. Re-posting the same national id updates the patient instead of duplicating it. Omitting internalCode keeps any value already stored.
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).
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. The {patient_id} can be the public id (sp_...) or the internalCode you set for your institution. Returns 404 if no patient with that id is visible to your key.
idCountry, idType, and idValue may be null for patients created outside this API that carry no identification.Updating a patient
PATCH /v1/patients/{patient_id} updates a patient’s name or internalCode, by its public id (sp_...) or internalCode. The national identity (idCountry/idType/idValue) is not editable here. Omit a field to leave it unchanged; send internalCode as null to clear it. Returns 404 if no patient with that id is visible to your key, and 409 if the internalCode is already used by another patient in your institution.
Deleting a patient
DELETE /v1/patients/{patient_id} deletes a patient by its public id (sp_...) or internalCode. Use it for right-to-erasure requests. Returns 204 on success, and 404 if no patient with that id is visible to your key.
A successful delete returns
204 with an empty body. A deleted patient is no longer returned by the list or get endpoints.