> ## 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.
# Quickstart
> Integrate with Telepatia's scribe in under 5 minutes
## Prerequisites
* A Telepatia API key (contact your account manager to obtain one)
* The base URL (see [Overview](/scribe-api/index))
The examples below use the production URL.
## Step 0: Pick (or build) a Smart Template
A **Smart Template** decides which sections Telepatia generates and how each one is shaped. Build it once with curated [Telepatia Prompts](/scribe-api/telepatia-nodes), reuse it across consultations.
List the Smart Templates already created for your account:
```bash theme={null}
curl https://scribe-api.telepatia.ai/v1/medical-record-configurations \
-H "Authorization: Bearer YOUR_API_KEY"
```
If you don't have one yet, create it. The example below uses two Telepatia Sections — see the [full catalog](/scribe-api/telepatia-nodes):
```bash theme={null}
curl -X POST https://scribe-api.telepatia.ai/v1/medical-record-configurations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "General Consultation",
"configuration": {
"chiefComplaint": {
"instructionSet": { "telepatiaPromptId": "CHIEF_COMPLAINT" },
"schema": {
"type": "object",
"instructions": "Chief complaint",
"properties": {
"chiefComplaint": { "type": "string", "instructions": "Patient words" }
}
}
},
"historyOfPresentIllness": {
"instructionSet": {
"telepatiaPromptId": "HISTORY_OF_PRESENT_ILLNESS",
"values": { "hpi_length": "long" }
},
"schema": {
"type": "object",
"instructions": "HPI",
"properties": {
"narrative": { "type": "string", "instructions": "Chronological HPI" }
}
}
}
}
}'
```
Save the returned `id` (e.g. `mrc_a1b2c3d4e5f6g7h8`) — you'll pass it to `set-consultation-context` next.
You can skip the explicit create and send the full JSON inline as `medicalRecordConfiguration` on `set-consultation-context`. Telepatia hashes it and dedups against existing templates automatically. See [Smart Templates](/scribe-api/smart-templates).
## Step 1: Set consultation context
Before the consultation, send the patient information to Telepatia. Include a `consultationInternalId` — your own identifier linking the session back to your system. If omitted, Telepatia generates one. Attach the Smart Template from Step 0 via `medicalRecordConfigurationId`.
```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 '{
"name": "John Doe",
"idCountry": "CO",
"idType": "CC",
"idValue": "123456789",
"notes": "Patient reports recurring headache and dizziness",
"pastMedicalHistory": "Hypertension diagnosed 2020. Diabetes Type 2 controlled with metformin.",
"consultationInternalId": "CONSULT-12345",
"scribeSessionModality": "IN_PERSON",
"medicalRecordConfigurationId": "mrc_a1b2c3d4e5f6g7h8"
}'
```
Legacy integrations can still pass `scribeSessionConfigurationId` instead — see [Session Templates](/scribe-api/session-templates). New integrations should use Smart Templates.
**Response:**
```json theme={null}
{
"success": true,
"consultationInternalId": "CONSULT-12345"
}
```
Save the `consultationInternalId` from the response. You will need it in the next steps — both to generate the login link and to retrieve the session results later.
## Step 2: Generate a login link
Generate a verification code to open the Telepatia scribe. Pass the `consultationInternalId` so the session is linked to the consultation context you set in Step 1.
```bash theme={null}
curl -X POST https://scribe-api.telepatia.ai/v1/auth/login \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"consultationInternalId": "CONSULT-12345"}'
```
**Response:**
```json theme={null}
{
"code": "a1b2c3d4e5",
"expiresAt": "2026-02-20T18:30:00+00:00",
"expiresIn": 300,
"redirectUrl": "https://scribe.telepatia.ai/sign-in?code=a1b2c3d4e5&consultationInternalId=CONSULT-12345"
}
```
Redirect the user to the `redirectUrl` to open the Telepatia scribe.
## Step 3: Conduct the session
Once the user is redirected, they will land in the Telepatia scribe interface. From there:
1. The scribe starts recording the consultation
2. The clinician conducts the visit as usual
3. When done, the clinician finishes the session in the scribe
No API calls are needed during this step — it all happens in the Telepatia app.
## Step 4: Retrieve the filled record
Step 4 has two parts: confirm the session is finished, then fetch the medical record documents (the filled output of your Smart Template).
### 4a. Check the session status
```bash theme={null}
curl https://scribe-api.telepatia.ai/v1/scribe-sessions/CONSULT-12345 \
-H "Authorization: Bearer YOUR_API_KEY"
```
**Response:**
```json theme={null}
{
"id": "ss_a1b2c3d4e5f6g7h8",
"status": "completed",
"createdAt": "2026-02-20T10:00:00Z",
"completedAt": "2026-02-20T10:30:00Z",
"patientName": "John Doe",
"scribeSessionModality": "IN_PERSON",
"consultationInternalId": "CONSULT-12345",
"specialty": "Cardiology"
}
```
Keep polling while `status` is in-flight (`created`, `recording`, `stopped`, `processing`). The documents are ready as soon as `status` becomes `completed` or `completedWithErrors`. `error` and `cancelled` mean no documents will be produced. See [Session lifecycle](/scribe-api/scribe-sessions#session-lifecycle) for the full list.
### 4b. Fetch the medical record documents
Once the session reaches `completed` or `completedWithErrors`, retrieve the filled record(s). One session can produce multiple documents (one per `purpose` — `primary`, `rpa`, `emr`, …). Filter with `?purpose=primary` to get the clinician-facing one:
```bash theme={null}
curl "https://scribe-api.telepatia.ai/v1/scribe-sessions/CONSULT-12345/medical-record-documents?purpose=primary" \
-H "Authorization: Bearer YOUR_API_KEY"
```
**Response:**
```json theme={null}
{
"items": [
{
"id": "mrd-abc-123",
"purpose": "primary",
"specialty": "Cardiology",
"language": "en",
"medicalRecordSummary": "Patient reports recurring headache and dizziness.",
"createdAt": "2026-02-20T10:30:00Z",
"updatedAt": "2026-02-20T10:35:00Z",
"medicalRecord": {
"sections": []
}
}
],
"total": 1
}
```
See [Medical Record Documents](/scribe-api/medical-record-documents) for the full response shape, including `medicalRecordSummaryStructured` and the available `purpose` values.