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

> Listar o buscar perfiles de pacientes por correo electrónico

Lista los perfiles de pacientes accesibles para tu clave de API o busca uno por su dirección de correo electrónico exacta.

Cuando se proporciona `email`, el endpoint realiza una búsqueda exacta en caché de Redis sobre el
correo electrónico canónico de inicio de sesión y devuelve 0 o 1 resultado; en ese caso se ignoran `limit` y `offset`.
Cuando se omite, el endpoint devuelve una lista paginada de perfiles limitada al contexto de acceso de tu
clave de API.

La coincidencia de correo electrónico es exacta y no distingue entre mayúsculas y minúsculas; no se admiten coincidencias parciales ni por prefijo.
Solo se comprueba el correo electrónico canónico de inicio de sesión; no se tienen en cuenta direcciones alternativas como `work_email`.

Requiere el ámbito `profiles_view` o `impersonate`.

## Solicitud

### Parámetros de consulta

**email** `string`

Filtra por dirección de correo electrónico exacta (sin distinguir entre mayúsculas y minúsculas). Si se indica, devuelve 0 o 1 resultado y
se ignoran `limit`/`offset`. La búsqueda se atiende mediante un índice inverso en caché de Redis, con
respaldo SQL indexado.

**limit** `integer` (default: 100)

Número máximo de perfiles que se devolverán. Por defecto es 100, máximo 500. Se ignora si se indica `email`.

**offset** `integer` (default: 0)

Número de perfiles que se omiten para la paginación. Por defecto es 0. Se ignora si se indica `email`.

## Respuesta

Si tiene éxito, la API devuelve `200 OK` con un array de objetos de perfil. La estructura de cada
elemento coincide con [Obtener perfil](https://docs.anivahealth.com/es/api/profiles/get-profile.md).

**id** `string` *required*

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`

Apellidos. 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 (`0` = desconocido, `1` = masculino, `2` = femenino). 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: `en`, `bg`, `ca`, `cs`, `da`, `de`, `el`, `es`, `et`, `fi`, `fr`, `ga`, `hr`, `hu`, `is`, `it`, `lb`, `lt`, `lv`, `mt`, `nl`, `no`, `pl`, `pt`, `ro`, `ru`, `sk`, `sl`, `sr`, `sv`, `tr` o `uk`.

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

Indica si este perfil recibe correos electrónicos transaccionales (programáticos). `null` si nunca se ha configurado.

**created\_at** `string`

Marca de tiempo ISO 8601 de creación del perfil.

**updated\_at** `string`

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

## Notas de comportamiento

* Se devuelve un array vacío tanto cuando ningún perfil coincide con el correo electrónico como cuando existe una coincidencia
  fuera de tu contexto de acceso. Esto es intencionado: evita que el endpoint revele la
  existencia de perfiles que no puedes leer.
* Los perfiles recién creados se pueden encontrar de inmediato por `email` porque el flujo de creación
  precarga la caché de forma síncrona.
* La lista sin filtrar se ordena por `created_at` de forma descendente (los más recientes primero) y se pagina mediante
  `limit` y `offset`.

## 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 `profile.created`, `profile.updated` y `profile.deleted`.
Consulta [Lecturas repetidas](https://docs.anivahealth.com/es/concepts/webhooks.md#lecturas-repetidas).

## Respuestas de error

| Estado | Descripción |
| - | - |
| `400` | Error de validación: formato de correo electrónico no válido o `limit`/`offset` fuera de rango. |
| `403` | Prohibido: tu clave de API no tiene el ámbito necesario (`profiles_view`/`impersonate`). |
| `500` | Error interno del servidor. |

```bash cURL (lookup by email) theme={null}
curl --request GET \
  --url 'https://anivahealth.com/api/v1/profiles?email=maria.schmidt@example.com' \
  --header 'x-api-key: YOUR_API_KEY'
```

```bash cURL (paginated list) theme={null}
curl --request GET \
  --url 'https://anivahealth.com/api/v1/profiles?limit=50&offset=0' \
  --header 'x-api-key: YOUR_API_KEY'
```

```json 200 theme={null}
[
  {
    "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": "2026-04-01T11:05:00Z"
  }
]
```

```json 200 (no match) theme={null}
[]
```

```json 400 theme={null}
{
  "error": "email: Invalid email format"
}
```


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