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

# Elenca profili

> Elenca o cerca i profili paziente per email

Elenca i profili paziente accessibili alla tua chiave API o cercane uno per indirizzo email esatto.

Quando `email` è fornito, l'endpoint esegue una ricerca esatta con cache Redis sull'email
canonica di accesso e restituisce 0 o 1 risultato; in quel caso `limit` e `offset` vengono
ignorati. Quando è omesso, l'endpoint restituisce un elenco paginato di profili limitato al
contesto di accesso della tua chiave API.

La corrispondenza dell'email è esatta e non distingue tra maiuscole e minuscole — le ricerche per
sottostringa o prefisso non sono supportate. Viene controllata solo l'email canonica di accesso;
indirizzi alternativi come `work_email` non vengono considerati.

Richiede lo scope `profiles_view` o `impersonate`.

## Richiesta

### Parametri di query

**email** `string`

Filtra per indirizzo email esatto (senza distinzione tra maiuscole e minuscole). Quando è impostato,
restituisce 0 o 1 risultato e `limit`/`offset` vengono ignorati. La ricerca è servita da un indice
inverso in cache Redis, con fallback SQL indicizzato.

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

Numero massimo di profili da restituire. Valore predefinito 100, massimo 500. Ignorato quando `email` è impostato.

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

Numero di profili da saltare per la paginazione. Valore predefinito 0. Ignorato quando `email` è impostato.

## Risposta

In caso di successo, l'API restituisce `200 OK` con un array di oggetti profilo. La struttura di ogni
elemento corrisponde a [Ottieni profilo](https://docs.anivahealth.com/it/api/profiles/get-profile.md).

**id** `string` *required*

Identificativo univoco del profilo (UUID).

**handle** `string`

Handle o nome utente del profilo. Può essere `null`.

**first\_name** `string`

Nome. Può essere `null`.

**last\_name** `string`

Cognome. Può essere `null`.

**email** `string`

Indirizzo email. Può essere `null`.

**phone** `string`

Numero di telefono in formato E.164. Può essere `null`.

**sex** `integer`

Sesso biologico secondo ISO/IEC 5218 (`0` = sconosciuto, `1` = maschio, `2` = femmina). Può essere `null`.

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

Data di nascita in formato `YYYY-MM-DD`. Può essere `null`.

**height** `number`

Altezza in centimetri. Può essere `null`.

**weight** `number`

Peso in chilogrammi. Può essere `null`.

**language** `string`

Lingua preferita: `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 se questo profilo riceve email transazionali (programmatiche). `null` se non è mai stato impostato.

**created\_at** `string`

Timestamp ISO 8601 della creazione del profilo.

**updated\_at** `string`

Timestamp ISO 8601 dell'ultimo aggiornamento. Può essere `null`.

## Note sul comportamento

* Viene restituito un array vuoto sia quando nessun profilo corrisponde all'email, sia quando esiste
  una corrispondenza fuori dal tuo contesto di accesso. È intenzionale — evita che l'endpoint riveli
  l'esistenza di profili che non puoi leggere.
* I profili appena creati sono immediatamente trovabili tramite `email` perché il flusso di creazione
  popola la cache in modo sincrono.
* L'elenco non filtrato è ordinato per `created_at` decrescente (i più recenti prima) e paginato tramite
  `limit` e `offset`.

## Chiamate ripetute

Aniva salva la risposta di questo endpoint per 5 minuti per ogni chiave API. Una chiamata ripetuta
in questo intervallo riceve la risposta salvata. Gli header `Cache-Status` e `Age` indicano che la risposta è
salvata e da quanto tempo.

Per sapere subito di una modifica, iscriviti agli eventi webhook `profile.created`, `profile.updated` e `profile.deleted`.
Vedi [Letture ripetute](https://docs.anivahealth.com/it/concepts/webhooks.md#letture-ripetute).

## Risposte di errore

| Stato | Descrizione |
| - | - |
| `400` | Errore di validazione — formato email non valido, oppure `limit`/`offset` fuori intervallo. |
| `403` | Accesso negato — la tua chiave API non ha lo scope richiesto (`profiles_view`/`impersonate`). |
| `500` | Errore interno del server. |

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