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

# Crea profilo

> Crea un nuovo profilo paziente e assegnalo a un gruppo di profili

Crea un nuovo profilo paziente e assegnalo a un gruppo di profili. Il profilo contiene i dati anagrafici usati per appuntamenti e ordini di laboratorio.

Richiede lo scope `create_user`.

Invia un header opzionale `Idempotency-Key` per poter ripetere questa creazione in sicurezza — ripetere la stessa chiave restituisce la risposta originale invece di crearne una seconda. Vedi [Idempotenza](https://docs.anivahealth.com/it/concepts/idempotency.md).

## Richiesta

### Parametri del body

**first\_name** `string` *required*

Nome del paziente. Deve usare caratteri latini, tra 1 e 100 caratteri.

**last\_name** `string` *required*

Cognome del paziente. Deve usare caratteri latini, tra 1 e 100 caratteri. I laboratori rifiutano
gli ordini per un paziente senza cognome, quindi non è possibile creare un profilo senza cognome.

Tre valori sono riservati per generare dati di test — vedi [Dati di test sandbox](#dati-di-test-sandbox).

**sex** `integer` *required*

Sesso biologico secondo ISO/IEC 5218. Usa `1` per maschio, `2` per femmina. Il laboratorio ne ha
bisogno per gli intervalli di riferimento, quindi `0` (sconosciuto) restituisce `400`. Obbligatorio,
a meno che il tuo gruppo di profili non consenta al paziente di inserirlo nella pagina di
attivazione del kit. In quel caso omettilo. Vedi
[Consenti al paziente di inserire data di nascita e sesso](https://docs.anivahealth.com/it/concepts/profiles.md#consenti-al-paziente-di-inserire-data-di-nascita-e-sesso).

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

Data di nascita nel formato `YYYY-MM-DD`. Deve essere nel passato e non prima del 1900. L'età
corrispondente deve essere compresa tra 16 e 100 anni. Altri valori restituiscono `400`.
Obbligatoria, a meno che il tuo gruppo di profili non consenta al paziente di inserirla nella
pagina di attivazione del kit. In quel caso omettila.

**profile\_group** `string` *required*

Riferimento polimorfico (UUID o slug) al gruppo di profili a cui assegnare questo profilo. L'UUID
è l'identificatore immutabile e resta valido anche se lo slug viene rinominato; lo slug resta
accettato per integrazioni di marketing e dei partner basate su identificatori leggibili. L'UUID è
preferibile. Il gruppo di profili deve rientrare nel contesto di accesso della tua chiave API.
Obbligatorio, a meno che tu non invii il campo deprecato `profile_group_slug`.

**profile\_group\_slug** `string` *deprecated*

Deprecato: usa `profile_group`. Slug del gruppo di profili. Solo lettere minuscole, cifre,
trattini e underscore.

**email** `string`

Indirizzo email del profilo. Se omesso, Aniva genera automaticamente un indirizzo email.

Fornire `email` rende la creazione anche **sicura in caso di nuovi tentativi**: un indirizzo può avere un solo profilo, quindi
una richiesta ripetuta restituisce `409` invece di un secondo profilo. Gli indirizzi generati automaticamente sono univoci per
richiesta. Invia `email` o un `Idempotency-Key` se la tua integrazione riprova.

**phone** `string`

Numero di telefono in formato E.164 (ad es. `+14155552671`).

**height** `number`

Altezza in centimetri.

**weight** `number`

Peso in chilogrammi.

**language** `string` (default: en)

Lingua preferita per il profilo: `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`. Il valore predefinito è `en`.

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

Indica se questo profilo deve ricevere email transazionali (automatiche) — conferme degli
appuntamenti, notifiche di risultati pronti, ecc. Sovrascrive il valore predefinito del gruppo di
profili. Distinto dal consenso al marketing. Ometti per usare il valore predefinito.

**marketing\_emails\_enabled** `boolean`

Indica se questo profilo acconsente alle email di marketing (newsletter, aggiornamenti di
prodotto). Sovrascrive il valore predefinito del gruppo di profili. Distinto dalle email
transazionali. Ometti per usare il valore predefinito del gruppo di profili. Solo in scrittura:
non viene restituito nella risposta del profilo.

## Dati di test sandbox

Ogni percorso di lettura utile da testare — [Elenca appuntamenti](https://docs.anivahealth.com/it/api/appointments/list-appointments.md),
[Ottieni risultati](https://docs.anivahealth.com/it/api/appointments/get-results.md),
[Scarica documento](https://docs.anivahealth.com/it/api/documents/download-document.md) — è vuoto finché non avviene un vero prelievo
di sangue giorni dopo. Questo rende scomodo scrivere un test di integrazione automatizzato.

Tre valori di `last_name` sono riservati per risolvere questo problema. Crea un profilo con uno di
questi valori e Aniva precompila lo stato descritto di seguito prima di rispondere, così la tua
chiamata successiva lo vede già:

| `last_name` | Cosa riceve il profilo |
| - | - |
| `Upcomingtestmann` | Un appuntamento futuro `confirmed` con un pannello associato. Nessun risultato ancora. |
| `Partialtestmann` | Un appuntamento passato `blood_drawn`. Circa **metà** del pannello è refertata; [Ottieni risultati](https://docs.anivahealth.com/it/api/appointments/get-results.md) è `in_progress`. |
| `Fulltestmann` | Un appuntamento passato `blood_drawn`. **Ogni** biomarcatore del pannello è refertato, `status: "completed"`, e un referto di laboratorio in PDF in `documents[]`. |

La corrispondenza non fa distinzione tra maiuscole e minuscole. Ogni altro campo — inclusi
`date_of_birth` e `sex` — viene salvato e usato normalmente, quindi gli intervalli di riferimento
che ricevi sono quelli reali specifici per età e sesso del profilo che hai creato.

L'appuntamento viene prenotato nella sede **Aniva Test**, in uno slot reale prenotabile tra almeno
cinque giorni (o cinque giorni fa, per gli stati passati). Generarlo non invia alcun ordine di laboratorio
e non prenota alcun corriere.

> [!NOTE]
>
> Assegna ai profili di test un indirizzo che controlli. I promemoria degli appuntamenti di Aniva si
> basano su `scheduled_at`, quindi la fixture futura li invierà a meno che non vengano disattivati sul
> profilo con `transactional_emails_enabled: false`.

Il pannello viene scelto casualmente tra quelli visibili alla tua chiave API, quindi il suo `panel_id` trova
sempre riscontro nel tuo [Elenca pannelli](https://docs.anivahealth.com/it/api/panels/list-panels.md). I biomarcatori clinici ricevono un valore
compreso nell'intervallo di riferimento del biomarcatore; i geni ricevono un genotipo casuale dai dati di riferimento di Aniva, con le relative varianti, la significatività clinica e gli ID rs che ne derivano.

> [!NOTE]
>
> Il pannello e i valori vengono rigenerati a ogni creazione, quindi verifica la struttura invece di un
> pannello specifico o di numeri esatti.

## Risposta

In caso di successo, l'API restituisce `201 Created` con il profilo appena creato.

**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, uno dei 32 codici sopra.

**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. `null` per i profili appena creati.

## Risposte di errore

| Stato | Descrizione |
| - | - |
| `400` | Errore di validazione — uno o più campi non hanno superato la validazione. |
| `403` | Accesso negato — la tua chiave API non ha accesso a questa operazione o il gruppo di profili è fuori dal tuo contesto di accesso. |
| `404` | Gruppo di profili non trovato. |
| `409` | Esiste già un profilo per l'`email` fornita (la risposta include l'indirizzo) o per la stessa persona (vedi sotto), oppure la `Idempotency-Key` è stata riutilizzata con un body diverso o la sua richiesta originale non è ancora completata. |
| `500` | Errore interno del server. |

Un `409` ha questo aspetto — interpretalo come "questo profilo esiste già" e cercalo con
[Elenca profili](https://docs.anivahealth.com/it/api/profiles/list-profiles.md) (`?email=`) invece di riprovare la creazione:

```json theme={null}
{
  "error": "An account with the email \"maria.schmidt@example.com\" already exists.",
  "error_name": "email_exists_error",
  "email": "maria.schmidt@example.com"
}
```

Una persona con lo stesso nome, cognome, sesso e data di nascita di un profilo visibile alla tua chiave
riceve un `409` con `error_name: "duplicate_profile_error"`. Usa il `profile_id` restituito invece di
creare un secondo profilo:

```json theme={null}
{
  "error": "A patient named \"Maria Schmidt\", born 02-04-1990, with the same biological sex already exists as m***@example.com. Search for that patient and select them instead of creating a duplicate.",
  "error_name": "duplicate_profile_error",
  "profile_id": "3f1c2a8e-5b7d-4c9e-8a21-6d4f0b9e7c35",
  "full_name": "Maria Schmidt",
  "date_of_birth": "1990-04-02",
  "masked_email": "m***@example.com"
}
```

I cognomi sandbox che generano i dati di test sono esclusi.

```bash cURL theme={null}
curl --request POST \
  --url https://anivahealth.com/api/v1/profiles \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "first_name": "Maria",
    "last_name": "Schmidt",
    "sex": 2,
    "date_of_birth": "1985-03-22",
    "profile_group": "acme-clinic-berlin",
    "email": "maria.schmidt@example.com",
    "phone": "+4930123456789",
    "height": 168,
    "weight": 65,
    "language": "de",
    "transactional_emails_enabled": true,
    "marketing_emails_enabled": false
  }'
```

```json 201 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": null
}
```

```json 400 theme={null}
{
  "error": "date_of_birth: Birthdate cannot be in the future."
}
```

```json 404 theme={null}
{
  "error": "Profile group 'acme-clinic-berlin' not found"
}
```


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