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

# Profili

> Come funzionano i profili dei pazienti nell'Aniva Partner API: crea, aggiorna e collega le persone per cui prenoti esami del sangue e kit domiciliari.

Un profilo è un record che rappresenta un paziente o un utente nel sistema Aniva. Ogni appuntamento, ordine di laboratorio e risultato è associato a un profilo.

## Gruppi di profili

Quando crei un profilo, lo assegni a un **gruppo di profili** tramite il parametro `profile_group`. Un gruppo di profili organizza i profili nel tuo account partner, associandoli a un programma o a un'integrazione specifica.

Il campo `profile_group` accetta l'UUID immutabile del gruppo oppure il suo slug leggibile. L'UUID è il riferimento permanente — non cambia mai e rimane valido anche se lo slug viene rinominato. Lo slug è pensato per URL leggibili e integrazioni partner.

Alla creazione è obbligatorio un valore `profile_group` (UUID o slug). Il campo legacy `profile_group_slug` continua a essere accettato come alias deprecato.

## Campi

**id** `string` *required*

UUID generato automaticamente da Aniva. Usalo per fare riferimento al profilo in altre chiamate API.

**handle** `string`

Nome utente o handle facoltativo per il profilo. Può essere null.

**first\_name** `string`

Nome del paziente. Solo caratteri latini, da 1 a 100 caratteri. Obbligatorio alla creazione.

**last\_name** `string`

Cognome del paziente. Solo caratteri latini, da 1 a 100 caratteri. Obbligatorio alla creazione — i
laboratori rifiutano gli ordini per un paziente senza cognome. Può essere null sui profili creati
prima che diventasse obbligatorio.

**email** `string`

Indirizzo email del paziente. Se non ne fornisci uno alla creazione, Aniva genera automaticamente
un'email segnaposto.

**phone** `string`

Numero di telefono in [formato E.164](https://www.itu.int/rec/T-REC-E.164/en) (es.
`+14155552671`). Può essere null.

**sex** `integer`

Sesso biologico secondo [ISO/IEC 5218](https://www.iso.org/standard/36266.html): `1` = maschio,
`2` = femmina. Obbligatorio alla creazione, a meno che il tuo gruppo di profili consenta al
paziente di inserirlo (vedi sotto). Il laboratorio ne ha bisogno per gli intervalli di
riferimento, quindi una creazione o un aggiornamento con `0` (sconosciuto) restituisce `400`. I
profili creati prima del 30 settembre 2026 possono ancora restituire `0`.

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

Data di nascita in formato `YYYY-MM-DD`. Obbligatoria alla creazione, a meno che il tuo gruppo di
profili consenta al paziente di inserirla (vedi sotto). Deve essere nel passato, non anteriore al
1900, e corrispondere a un'età tra 16 e 100 anni; i valori non plausibili vengono rifiutati con
`400`. La data di nascita viene inviata al laboratorio con l'ordine e non può essere modificata
una volta effettuato l'ordine.

**height** `number`

Altezza in centimetri. Può essere null.

**weight** `number`

Peso in chilogrammi. Può essere null.

**language** `string`

Lingua preferita per le comunicazioni rivolte al paziente. Valori accettati: `en`, `de`, `fi`.

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

Indica se il profilo riceve email transazionali, come conferme di appuntamento e notifiche di
risultati pronti. Distinto dal consenso marketing. Null se non è mai stato impostato.

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

Timestamp ISO 8601 della creazione del profilo.

**updated\_at** `string`

Timestamp ISO 8601 dell'aggiornamento più recente. Null se il profilo non è mai stato aggiornato.

> [!NOTE]
>
> I campi `first_name`, `last_name`, `sex`, `date_of_birth` e `profile_group` sono obbligatori
> quando crei un profilo. Tutti gli altri campi sono facoltativi. Il campo legacy
> `profile_group_slug` è ancora accettato come alias deprecato di `profile_group`.

### Consenti al paziente di inserire data di nascita e sesso

Possiamo attivare un'impostazione per il tuo gruppo di profili. In questo modo puoi creare un
profilo senza `date_of_birth` e `sex`. Chiedici di attivarla. Senza questa impostazione, una
creazione che omette uno dei due campi restituisce `400`.

Il paziente inserisce entrambi i dati nella pagina di attivazione del kit
(`anivahealth.com/activate`), insieme al codice del kit. La pagina chiede la data di nascita due
volte, perché il laboratorio non può modificarla in seguito. Dopodiché, il kit si apre solo con
quella data di nascita. Finché il paziente non inserisce entrambi i dati, teniamo in sospeso
l'ordine di laboratorio. Usa questa impostazione solo per i kit domiciliari.

## Ciclo di vita

I profili seguono un ciclo di vita semplice:

1. **Crea** — registra il profilo con i campi anagrafici obbligatori e un `profile_group` (UUID
   o slug).
2. **Aggiorna** (opzionale) — aggiungi o modifica campi come `phone`, `height` o `weight`.
3. **Associa** — collega il profilo agli appuntamenti usando il suo `id` come `profile_id`.

Un [webhook](https://docs.anivahealth.com/it/concepts/webhooks.md) `profile.*` ti avvisa quando un profilo appare, cambia o viene eliminato.

## Profilo di esempio

```json theme={null}
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "handle": "jdoe42",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane.doe@example.com",
  "phone": "+14155552671",
  "sex": 2,
  "date_of_birth": "1990-06-15",
  "height": 168.0,
  "weight": 65.0,
  "language": "en",
  "transactional_emails_enabled": true,
  "created_at": "2026-03-01T09:00:00Z",
  "updated_at": "2026-03-10T14:32:00Z"
}
```


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