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`.
`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	`IN_PERSON` or `TELEMEDICINE`
`notes`	No	Free-text clinical notes visible to the clinician
`pastMedicalHistory`	No	Patient’s medical history

Identify the patient either with the inline fields (name, idCountry, idType, idValue) or with patientId — never both. Referencing an existing patient by patientId reuses its stored identity, so you avoid re-sending it and never create a duplicate. Providing both, or an incomplete inline identity without patientId, returns a 400 error.

Accepted documents by country

Country	`idCountry`	Document	`idType`	Format
Colombia	`CO` / `COL` / `COLOMBIA`	Cédula de Ciudadanía	`CC`	8–10 digits
Colombia		Tarjeta de Identidad	`TI`	10–11 digits
Colombia		Cédula de Extranjería	`CE`	6–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"
  }'

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

Scribe Sessions

Clinical Decision Support

Webhooks

Smart Templates

Session Templates

Accounts

Patients

Reference

Consultations

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

​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

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