> ## Documentation Index
> Fetch the complete documentation index at: https://docs.telepatia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Consultations

> Set patient context before a scribe session

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](/scribe-api/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](/scribe-api/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                                                                                                                                                                           |

<Note>
  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.
</Note>

## 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 |

<Note>
  The `idType` must be valid for the given `idCountry`. For example, passing `CC` with `idCountry: BR` returns a `400` error.
</Note>

## 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)

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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:**

```json theme={null}
{
  "success": true,
  "consultationInternalId": "CONSULT-12345"
}
```

<Tip>
  Save the `consultationInternalId` — you'll need it to generate the login link and retrieve the session results.
</Tip>