Skip to main content
The consultation context call sends patient identity and clinical information to Telepatia before a session starts. Telepatia uses this data to pre-populate the patient record in the scribe interface and link the completed session back to your system. Call this endpoint before generating a login link. If you skip it, the scribe session will start without patient context.

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 by id

Example request — reference an existing patient

Example request — reference by internalCode and set the branch

Response:
Save the consultationInternalId — you’ll need it to generate the login link and retrieve the session results.

Clinical context

The clinicalContext 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:write permission. A legacy key with no permissions claim gets 403 for that block; regenerate the key to obtain one. A block with only currentEncounter.id keeps the access rules of the call.
  • The block works for every institution. It needs no setup: an API key with scribe:write that is bound to your institution is enough.
  • A block that holds only currentEncounter.id does 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

The response is the same as for every other call: { "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

  1. Updates by id. Telepatia writes each item, encounter and procedure by its id. A later call with the same id updates it. An item that the call does not send stays as it is. To remove one, send it again with ENTERED_IN_ERROR or INACTIVE.
  2. Previous encounters. Send a previous encounter once, and again only when it changes.
  3. The 409 rule. clinicalContext is not part of the check that returns 409. A call that repeats the same consultation with a different clinicalContext does not conflict.
  4. Order. Telepatia stores the consultation context first, then queues the clinical context write. The response does not wait for that write.
  5. The call never fails because of the clinical context. When Telepatia cannot queue the write, the call still returns 200 and 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.
  6. The patient of the block. Telepatia stores the block on the patient that the call resolves. A stored patient (a patientId, or an internalCode that 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 returns 200. Add the document to the patient, so that Telepatia can store the block.
  7. 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 that POST /v1/scribe-sessions/audio creates does not attach to the encounter, so its note does not read the block.

Errors

See Errors for the full response envelope.