Consultations

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

Field	Required	Description
`consultationInternalId`	No	Your internal ID for this consultation. If omitted, Telepatia generates one. Used to retrieve the session later.
`name`	Conditional	Patient full name. Required unless `patientId` is set.
`idCountry`	Conditional	Country of the ID document (ISO alpha-2, alpha-3, or full name). Required unless `patientId` is set.
`idType`	Conditional	Type of ID document (see table below). Required unless `patientId` is set.
`idValue`	Conditional	Document number. Required unless `patientId` is set.
`patientId`	Conditional	Public id of an existing patient (`sp_...`, from Patients). Use instead of the inline identity fields. Mutually exclusive with `name` / `idCountry` / `idType` / `idValue`.
`internalCode`	Conditional	Your own patient code, unique per institution. Looks up an existing patient by this code; if the code is new, the inline identity creates and tags the patient. Mutually exclusive with `patientId`.
`medicalRecordConfiguration`	No	Smart Template inline (recommended). Full JSON; server dedups by content hash. See Smart Templates.
`medicalRecordConfigurationId`	No	Smart Template by id (from `/v1/medical-record-configurations`).
`scribeSessionConfigurationId`	No	Legacy Session Template id (from `/v1/scribe-session-configurations`).
`scribeSessionModality`	No	What kind of session this is. `IN_PERSON` or `TELEMEDICINE` for a Scribe consultation, `DICTATION` for a dictated report.
`institutionalBranchId`	No	Id of the institution branch for this consultation, returned by the create-branch endpoint (`POST /v1/institutional/branches`). Stamped onto the session. Provide the id or the name.
`institutionalBranch`	No	Name of the institution branch. Used when `institutionalBranchId` is omitted. Provide the id or the name.
`notes`	No	Free-text clinical notes visible to the clinician
`pastMedicalHistory`	No	Patient’s medical history

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

Country	`idCountry`	Document	`idType`	Format
Colombia	`CO` / `COL` / `COLOMBIA`	Cédula de Ciudadanía	`CC`	5–10 digits
Colombia		Tarjeta de Identidad	`TI`	10–11 digits
Colombia		Cédula de Extranjería	`CE`	3–7 digits
Colombia		Registro Civil	`RC`	1–11 digits
Brazil	`BR` / `BRA` / `BRAZIL`	Registro Geral	`RG`	7–9 alphanumeric
Brazil		CPF	`CPF`	XXX.XXX.XXX-XX
Any	—	Passport	`PASSPORT`	6–9 alphanumeric
Any	—	Other	`OTHER_DOC`	Any non-empty string

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)

curl -X POST https://scribe-api.telepatia.ai/v1/set-consultation-context \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "consultationInternalId": "CONSULT-12345",
    "name": "John Doe",
    "idCountry": "CO",
    "idType": "CC",
    "idValue": "123456789",
    "notes": "Patient reports recurring headache",
    "pastMedicalHistory": "Hypertension diagnosed 2020",
    "scribeSessionModality": "IN_PERSON",
    "medicalRecordConfiguration": {
      "chiefComplaint": {
        "instructionSet": { "telepatiaPromptId": "CHIEF_COMPLAINT" },
        "schema": {
          "type": "object",
          "instructions": "Chief complaint",
          "properties": {
            "chiefComplaint": { "type": "string", "instructions": "Patient words" }
          }
        }
      }
    }
  }'

Example request — Smart Template by id

curl -X POST https://scribe-api.telepatia.ai/v1/set-consultation-context \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "consultationInternalId": "CONSULT-12345",
    "name": "John Doe",
    "idCountry": "CO",
    "idType": "CC",
    "idValue": "123456789",
    "scribeSessionModality": "IN_PERSON",
    "medicalRecordConfigurationId": "mrc_a1b2c3d4e5f6g7h8"
  }'

Example request — reference an existing patient

curl -X POST https://scribe-api.telepatia.ai/v1/set-consultation-context \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "consultationInternalId": "CONSULT-12345",
    "patientId": "sp_a1b2c3d4e5f6g7h8",
    "scribeSessionModality": "IN_PERSON"
  }'

Example request — reference by internalCode and set the branch

curl -X POST https://scribe-api.telepatia.ai/v1/set-consultation-context \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "consultationInternalId": "CONSULT-12345",
    "internalCode": "MRN-000123",
    "name": "John Doe",
    "idCountry": "CO",
    "idType": "CC",
    "idValue": "123456789",
    "institutionalBranch": "Sede Norte",
    "scribeSessionModality": "IN_PERSON"
  }'

Response:

{
  "success": true,
  "consultationInternalId": "CONSULT-12345"
}

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

Getting Started

Core Concepts

Accounts & Patients

Reference

Key fields

Accepted documents by country

Templates: pass exactly one

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

​Key fields

​Accepted documents by country

​Templates: pass exactly one

​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

Key fields

Accepted documents by country

Templates: pass exactly one

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