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

# Listar citas

> Obtener las citas de extracción de sangre accesibles con tu clave API

Obtén una lista de citas de extracción de sangre. Cada cita incluye el perfil del paciente integrado.

Los filtros se combinan:

* `date` devuelve las citas de un día natural. El día corresponde al día local de la ubicación de cada cita, por lo que una extracción de sangre a las 23:30 en Berlín cuenta con su fecha de Berlín.
* `location_id` devuelve las citas de una ubicación de pruebas.
* `profile_id` sin `date` devuelve todas las citas de ese perfil, sin restricción temporal.
* Sin `profile_id` ni `date`, se aplica la ventana temporal predeterminada: de los últimos 2 meses hasta dentro de 1 mes.

Requiere el scope `appointments_view` o `appointments_schedule`.

## Solicitud

### Parámetros de consulta

**profile\_id** `string`

Filtra por UUID de perfil. Cuando se proporciona, se devuelven todas las citas de este perfil sin importar
la fecha programada. Cuando se omite, se aplica la ventana temporal predeterminada.

**location\_id** `string`

Filtra por UUID de ubicación de pruebas.

**date** `string`

Día natural en formato `YYYY-MM-DD`, en la zona horaria de la ubicación de cada cita. Sustituye la
ventana temporal predeterminada. Los resultados se ordenan por `scheduled_at`, primero los más tempranos.

## Respuesta

Si tiene éxito, la API devuelve `200 OK` con un array de objetos de cita.

**id** `string` *required*

Identificador único de la cita (UUID).

**profile\_id** `string` *required*

UUID del perfil al que pertenece esta cita.

**location\_id** `string`

UUID del centro de análisis donde se realiza la extracción de sangre.

**scheduled\_at** `string`

Fecha y hora programadas de la cita como instante UTC (ISO 8601 con sufijo `Z`, p. ej.,
`2026-05-15T10:30:00Z`). Puede ser `null`.

**status** `string` *required*

Estado actual de la cita. Puede ser `pending`, `confirmed`, `blood_drawn` o `cancelled`. El grado
de avance de los resultados de laboratorio se obtiene en [Obtener resultados](https://docs.anivahealth.com/es/api/appointments/get-results.md);
el progreso detallado de los envíos, a partir de cada entrada del array `shipments` integrado (ver
más abajo) consultándolo en [Obtener envío](https://docs.anivahealth.com/es/api/shipments/get-shipment.md).

**cancellation\_reason** `string`

Motivo en texto libre registrado al cancelar la cita (p. ej., no presentado, cancelación tardía,
'Fallida. Repetición necesaria'). `null` salvo que `status` sea `cancelled`.

**results\_ready\_emails** `string[]` *required*

Direcciones que reciben un correo cada una cuando todos los resultados de laboratorio son definitivos, en minúsculas. Vacío cuando está desactivado. Consulta
[Correos de resultados listos](https://docs.anivahealth.com/es/concepts/results.md#correos-de-resultados-listos).

**draw\_method** `string` *required*

Cómo se realiza la extracción de sangre: `capillary` (en la yema del dedo o en la parte superior del brazo, en microtubos) o `venous` (de la vena,
en tubos). Es el método definido en la cita o, en su defecto, el `default_draw_method` de su
[ubicación](https://docs.anivahealth.com/es/concepts/locations.md). Después de la extracción de sangre, es el método que se utilizó.

**created\_at** `string` *required*

Marca de tiempo ISO 8601 de cuándo se creó la cita.

**updated\_at** `string`

Marca de tiempo ISO 8601 de la última actualización. Puede ser `null`.

**profile** `object` *required*

El perfil del paciente asociado a esta cita.

**perfil**

**id** `string`

Identificador único del perfil (UUID).

**handle** `string`

Alias o nombre de usuario del perfil. Puede ser `null`.

**first\_name** `string`

Nombre. Puede ser `null`.

**last\_name** `string`

Apellido. Puede ser `null`.

**email** `string`

Dirección de correo electrónico. Puede ser `null`.

**phone** `string`

Número de teléfono en formato E.164. Puede ser `null`.

**sex** `integer`

Sexo biológico según ISO/IEC 5218. Puede ser `null`.

**date\_of\_birth** `string`

Fecha de nacimiento en formato `YYYY-MM-DD`. Puede ser `null`.

**height** `number`

Altura en centímetros. Puede ser `null`.

**weight** `number`

Peso en kilogramos. Puede ser `null`.

**language** `string`

Idioma preferido: uno de los 32 códigos en [Crear perfil](https://docs.anivahealth.com/es/api/profiles/create-profile.md).

**transactional\_emails\_enabled** `boolean`

Indica si este perfil recibe correos transaccionales (programáticos). Puede ser `null`.

**created\_at** `string`

Marca de tiempo ISO 8601 de cuándo se creó el perfil.

**updated\_at** `string`

Marca de tiempo ISO 8601 de la última actualización del perfil. Puede ser `null`.

**panels** `AppointmentPanel[]` *required*

Paneles asociados actualmente a esta cita. Excluye las asociaciones canceladas. Consulta los detalles
del panel (nombre, biomarcadores) mediante [Listar paneles](https://docs.anivahealth.com/es/api/panels/list-panels.md).

**Campos de asociación de panel**

**panel\_id** `string`

UUID del panel: contrástalo con [Listar paneles](https://docs.anivahealth.com/es/api/panels/list-panels.md).

**added\_at** `string`

Marca de tiempo ISO 8601 en la que el panel se asoció por primera vez a esta cita.

**individual\_biomarkers** `AppointmentIndividualBiomarker[]` *required*

Biomarcadores a la carta asociados a esta cita fuera de cualquier panel (consulta [Añadir
biomarcadores personalizados](https://docs.anivahealth.com/es/api/appointments/add-individual-biomarkers.md)). Contrasta cada `biomarker_id`
con [Listar biomarcadores](https://docs.anivahealth.com/es/api/biomarkers/list-biomarkers.md) para obtener los datos de visualización.

**Campos de biomarcador individual**

**biomarker\_id** `integer`

Identificador del biomarcador: contrástalo con
[Listar biomarcadores](https://docs.anivahealth.com/es/api/biomarkers/list-biomarkers.md).

**added\_at** `string`

Marca de tiempo ISO 8601 en la que el biomarcador se asoció por primera vez a esta cita.

**shipments** `AppointmentShipmentLink[]` *required*

Envíos vinculados a esta cita, del vínculo más antiguo al más reciente. Array vacío cuando no hay envíos
vinculados. Cruza cada `id` con [Obtener envío](https://docs.anivahealth.com/es/api/shipments/get-shipment.md) para ver los
datos completos del envío (estado, número de seguimiento, actualizaciones de estado, etc.).

**Campos de vínculo de envío**

**id** `string`

Identificador de referencia del envío: contrástalo con
[Obtener envío](https://docs.anivahealth.com/es/api/shipments/get-shipment.md).

**added\_at** `string`

Marca de tiempo ISO 8601 en la que el envío se vinculó por primera vez a esta cita.

**lab\_codes** `string[]` *required*

Códigos de laboratorio (códigos de barras de los tubos) registrados para esta cita, en orden de escaneo. Vacío hasta que se confirme
la extracción de sangre. Una extracción venosa lleva un único código impreso en todos los tubos; una extracción capilar lleva un
código por microtubo. Los resultados y documentos de [Obtener resultados](https://docs.anivahealth.com/es/api/appointments/get-results.md) hacen referencia
a estos códigos mediante `lab_code`.

## Llamadas repetidas

Aniva almacena la respuesta de este endpoint durante 5 minutos para cada clave de API. Una llamada repetida dentro
de este plazo obtiene la respuesta almacenada. Las cabeceras `Cache-Status` y `Age` indican que la respuesta está
almacenada y cuál es su antigüedad.

Para enterarte de un cambio al instante, suscríbete a los eventos de webhook `appointment.created`, `appointment.rescheduled` y al evento de cada estado, por ejemplo `appointment.confirmed`.
Consulta [Lecturas repetidas](https://docs.anivahealth.com/es/concepts/webhooks.md#lecturas-repetidas).

## Respuestas de error

| Estado | Descripción |
| - | - |
| `400` | Parámetro de consulta no válido, por ejemplo un `date` que no sea `YYYY-MM-DD`. |
| `403` | Prohibido: tu clave de API no tiene acceso a esta operación, o el perfil o la ubicación solicitados están fuera de tu ámbito de permisos. |
| `500` | Error interno del servidor. |

```bash cURL (all appointments) theme={null}
curl --request GET \
  --url https://anivahealth.com/api/v1/appointments \
  --header 'x-api-key: YOUR_API_KEY'
```

```bash cURL (one day at one location) theme={null}
curl --request GET \
  --url 'https://anivahealth.com/api/v1/appointments?date=2026-10-21&location_id=b7e2d1f5-3c4a-4e8b-a2f1-9d0c1e2f3a4b' \
  --header 'x-api-key: YOUR_API_KEY'
```

```bash cURL (by profile) theme={null}
curl --request GET \
  --url 'https://anivahealth.com/api/v1/appointments?profile_id=a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d' \
  --header 'x-api-key: YOUR_API_KEY'
```

```json 200 theme={null}
[
  {
    "id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
    "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
    "location_id": "b7e2d1f5-3c4a-4e8b-a2f1-9d0c1e2f3a4b",
    "scheduled_at": "2026-05-15T10:30:00Z",
    "status": "confirmed",
    "cancellation_reason": null,
    "results_ready_emails": [],
    "draw_method": "venous",
    "created_at": "2026-04-01T09:45:00Z",
    "updated_at": null,
    "profile": {
      "id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
      "handle": null,
      "first_name": "Maria",
      "last_name": "Schmidt",
      "email": "maria.schmidt@example.com",
      "phone": "+4930123456789",
      "sex": 2,
      "date_of_birth": "1985-03-22",
      "height": 168,
      "weight": 65,
      "language": "de",
      "transactional_emails_enabled": true,
      "created_at": "2026-04-01T09:14:32Z",
      "updated_at": null
    },
    "panels": [
      {
        "panel_id": "f1c2d4a3-7b8e-4f2a-9c1d-2e3f4a5b6c7d",
        "added_at": "2026-04-01T09:50:00Z"
      }
    ],
    "individual_biomarkers": [
      {
        "biomarker_id": 42,
        "added_at": "2026-04-01T09:52:00Z"
      }
    ],
    "shipments": [
      {
        "id": "P2611194821",
        "added_at": "2026-04-15T07:00:00Z"
      }
    ],
    "lab_codes": []
  }
]
```

```json 403 theme={null}
{
  "error": "Access denied: profile is outside your permission scope"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.