Key fields
Identify the patient in one of three ways: the inline fields (
name, idCountry, idType, idValue), an existing patientId (sp_...), or your own internalCode. patientId cannot be combined with the inline identity or internalCode. internalCode may be sent alone to reference an existing patient, or together with the full inline identity, which creates and tags the patient when the code is new. Providing both patientId and the inline identity, or an incomplete inline identity, returns a 400 error.Accepted documents by country
The
idType must be valid for the given idCountry. For example, passing CC with idCountry: BR returns a 400 error.Templates: pass exactly one
medicalRecordConfiguration, medicalRecordConfigurationId, and scribeSessionConfigurationId are mutually exclusive — pass at most one. We recommend the inline medicalRecordConfiguration form: it’s reproducible, lets you version the template alongside your code, and the server dedups by content hash so you don’t accumulate duplicates.
Example request — Smart Template inline (recommended)
Example request — Smart Template by id
Example request — reference an existing patient
Example request — reference by internalCode and set the branch
Clinical context
TheclinicalContext block sends the clinical data your system already holds for the patient: allergies, medications, conditions, the current encounter (chief complaint, triage, vital signs, diagnoses, procedures and notes) and previous encounters. Telepatia stores the block in the patient record. The AI reads it when it writes the note of the session, so the note names the right medications, allergies and history.
Send the block in the same call that sets the patient and the consultation. The other fields of the request do not change.
Access
- A block with clinical data needs a doctor API key with the
scribe:writepermission. A legacy key with no permissions claim gets403for that block; regenerate the key to obtain one. A block with onlycurrentEncounter.idkeeps the access rules of the call. - The block works for every institution. It needs no setup: an API key with
scribe:writethat is bound to your institution is enough. - A block that holds only
currentEncounter.iddoes not need the feature. It attaches the session to that encounter, as before, and writes nothing to the patient record.
Example request — full clinical context
{ "success": true, "consultationInternalId": "CONSULTA-12345" }.
clinicalContext fields
Field names are camelCase. A field that Telepatia does not know, inside
clinicalContext, returns 400: the block holds clinical data, so a wrong field name must not disappear in silence.
Items: allergies, medications, conditions and diagnoses
The same shape applies to the four lists.
Only
ENTERED_IN_ERROR removes a diagnosis from the encounter history.
Procedures
A procedure is{ "id", "name", "code" } and exists only inside an encounter. code is optional. The procedure takes the date of its encounter. Its status accepts only ENTERED_IN_ERROR, to remove a procedure sent by mistake.
Encounters
The defaults of
class and startedAt apply only to the first write of an encounter.
Vital signs
Code systems
An unknown
system returns 400.
How Telepatia applies the block
- Updates by id. Telepatia writes each item, encounter and procedure by its
id. A later call with the sameidupdates it. An item that the call does not send stays as it is. To remove one, send it again withENTERED_IN_ERRORorINACTIVE. - Previous encounters. Send a previous encounter once, and again only when it changes.
- The
409rule.clinicalContextis not part of the check that returns409. A call that repeats the same consultation with a differentclinicalContextdoes not conflict. - Order. Telepatia stores the consultation context first, then queues the clinical context write. The response does not wait for that write.
- The call never fails because of the clinical context. When Telepatia cannot queue the write, the call still returns
200and Telepatia alerts its team. The block of that call is not stored. Your next call for the same encounter sends the block again, so send the current encounter on every call. - The patient of the block. Telepatia stores the block on the patient that the call resolves. A stored patient (a
patientId, or aninternalCodethat matches a patient) keeps its stored identity document, also when the call sends different inline identity fields. A stored patient with no identity document gets no clinical context write, and the call still returns200. Add the document to the patient, so that Telepatia can store the block. - The session that reads the block. The session that the doctor starts in Telepatia after this call attaches to
currentEncounter, and its note reads the block. A session thatPOST /v1/scribe-sessions/audiocreates does not attach to the encounter, so its note does not read the block.
Errors
See Errors for the full response envelope.