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

# Pacientes

> Crea, lista y consulta pacientes por su id público estable

Los pacientes son las personas sobre las que tratan tus sesiones de scribe. Crea un paciente una vez y reutiliza su id público estable (`sp_...`) en todas las consultas, en lugar de reenviar los campos de identidad cada vez.

Los campos de identidad (`name`, `idCountry`, `idType`, `idValue`) son los mismos que usa [set-consultation-context](/es/scribe-api/consultations) y siguen las mismas reglas de validación — consulta [Documentos aceptados por país](/es/scribe-api/consultations#accepted-documents-by-country).

<Note>
  Los pacientes están **acotados por el rol de tu clave API**: una clave de médico solo ve sus propios pacientes; una clave institucional ve a todos los pacientes de su institución. Nunca necesitas pasar un id de cuenta o institución — el alcance se aplica en el servidor.
</Note>

## Crear un paciente

`POST /v1/patients` requiere `name`, `idCountry`, `idType` e `idValue`. El `idType` debe ser válido para el `idCountry` dado (p. ej., `CC` con `idCountry: BR` devuelve `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"
  }'
```

**Respuesta:**

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

<Tip>
  Guarda el `id` (`sp_...`) — es estable y reutilizable. Crear un paciente con un documento de identidad que ya existe devuelve el paciente existente en lugar de un duplicado.
</Tip>

## Listar pacientes

`GET /v1/patients` devuelve los pacientes visibles para tu clave, del más reciente al más antiguo. Pagina con `page` (base 1) y `limit` (1–50, por defecto 20).

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

**Respuesta:**

```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` y `totalPages` solo se calculan en la **primera página** — son `null` en las páginas siguientes para evitar un escaneo completo en cada clic. Usa `hasMore` para paginar de forma fiable; es preciso en todas las páginas.
</Note>

## Consultar un paciente

`GET /v1/patients/{patient_id}` busca un único paciente por su id público (`sp_...`). Devuelve `404` si ningún paciente con ese id es visible para tu clave.

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

**Respuesta:**

```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` e `idValue` pueden ser `null` para pacientes creados fuera de esta API que no llevan identificación.
</Note>