Quickstart

Prerequisites

A Telepatia API key (contact your account manager to obtain one)
The base URL (see Overview)

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, reuse it across consultations. List the Smart Templates already created for your account:

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:

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.

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.

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. New integrations should use Smart Templates.

Response:

{
  "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.

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.

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:

{
  "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:

The scribe starts recording the consultation
The clinician conducts the visit as usual
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

curl https://scribe-api.telepatia.ai/v1/scribe-sessions/CONSULT-12345 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "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 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:

curl "https://scribe-api.telepatia.ai/v1/scribe-sessions/CONSULT-12345/medical-record-documents?purpose=primary" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "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 for the full response shape, including medicalRecordSummaryStructured and the available purpose values.

Getting Started

Consultations

Scribe Sessions

Clinical Decision Support

Webhooks

Smart Templates

Session Templates

Accounts

Patients

Reference

Prerequisites

Step 0: Pick (or build) a Smart Template

Step 1: Set consultation context

Step 3: Conduct the session

Step 4: Retrieve the filled record

4a. Check the session status

4b. Fetch the medical record documents

​Prerequisites

​Step 0: Pick (or build) a Smart Template

​Step 1: Set consultation context

​Step 2: Generate a login link

​Step 3: Conduct the session

​Step 4: Retrieve the filled record

​4a. Check the session status

​4b. Fetch the medical record documents

Prerequisites

Step 0: Pick (or build) a Smart Template

Step 1: Set consultation context

Step 2: Generate a login link

Step 3: Conduct the session

Step 4: Retrieve the filled record

4a. Check the session status

4b. Fetch the medical record documents