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

# Patients

> Create, list, and retrieve patients by their stable public id

Patients are the people your scribe sessions are about. Create a patient once and reuse its stable public id (`sp_...`) across consultations, instead of re-sending identity fields every time.

The identity fields (`name`, `idCountry`, `idType`, `idValue`) are the same ones used by [set-consultation-context](/scribe-api/consultations) and follow the same validation rules — see [Accepted documents by country](/scribe-api/consultations#accepted-documents-by-country).

<Note>
  Patients are **tenant-scoped by your API key's role**: a doctor key sees only its own patients; an institutional key sees every patient within its institution. You never need to pass an account or institution id — scoping is enforced server-side.
</Note>

## Creating a patient

`POST /v1/patients` requires `name`, `idCountry`, `idType`, and `idValue`. The `idType` must be valid for the given `idCountry` (e.g. `CC` with `idCountry: BR` returns `400`).

```bash theme={null}
curl -X POST https://scribe-api.telepatia.ai/v1/patients \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "idCountry": "CO",
    "idType": "CC",
    "idValue": "1024567890"
  }'
```

**Response:**

```json theme={null}
{
  "id": "sp_a1b2c3d4e5f6g7h8",
  "name": "John Doe",
  "idCountry": "COLOMBIA",
  "idType": "CC",
  "idValue": "1024567890",
  "createdAt": "2026-07-01T12:00:00.000Z"
}
```

<Tip>
  Save the `id` (`sp_...`) — it's stable and reusable. Creating a patient with an identity document that already exists returns the existing patient rather than a duplicate.
</Tip>

## Listing patients

`GET /v1/patients` returns the patients visible to your key, most recent first. Paginate with `page` (1-based) and `limit` (1–50, default 20).

```bash theme={null}
curl "https://scribe-api.telepatia.ai/v1/patients?page=1&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response:**

```json theme={null}
{
  "items": [
    {
      "id": "sp_a1b2c3d4e5f6g7h8",
      "name": "John Doe",
      "idCountry": "COLOMBIA",
      "idType": "CC",
      "idValue": "1024567890",
      "createdAt": "2026-07-01T12:00:00.000Z"
    }
  ],
  "total": 137,
  "page": 1,
  "limit": 20,
  "totalPages": 7,
  "hasMore": true
}
```

<Note>
  `total` and `totalPages` are only computed on the **first page** — they are `null` on later pages to avoid a full scan on every page click. Use `hasMore` to paginate reliably; it is accurate on every page.
</Note>

## Retrieving a patient

`GET /v1/patients/{patient_id}` looks up a single patient by its public id (`sp_...`). Returns `404` if no patient with that id is visible to your key.

```bash theme={null}
curl https://scribe-api.telepatia.ai/v1/patients/sp_a1b2c3d4e5f6g7h8 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response:**

```json theme={null}
{
  "id": "sp_a1b2c3d4e5f6g7h8",
  "name": "John Doe",
  "idCountry": "COLOMBIA",
  "idType": "CC",
  "idValue": "1024567890",
  "createdAt": "2026-07-01T12:00:00.000Z"
}
```

<Note>
  `idCountry`, `idType`, and `idValue` may be `null` for patients created outside this API that carry no identification.
</Note>