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

# Criar perfil

> Criar um novo perfil de paciente e atribuí-lo a um grupo de perfis

Cria um novo perfil de paciente e atribui-o a um grupo de perfis. O perfil guarda dados demográficos usados em marcações e pedidos laboratoriais.

Requer o scope `create_user`.

Envia um cabeçalho opcional `Idempotency-Key` para tornar esta criação segura para repetir — repetir a mesma chave devolve a resposta original em vez de criar outra. Vê [Idempotência](https://docs.anivahealth.com/pt/concepts/idempotency.md).

## Pedido

### Parâmetros do corpo

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

Nome próprio do paciente. Tem de usar caracteres latinos, entre 1 e 100 caracteres.

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

Apelido do paciente. Tem de usar caracteres latinos, entre 1 e 100 caracteres. Os laboratórios
rejeitam pedidos para um paciente sem apelido, pelo que não é possível criar um perfil sem um.

Três valores estão reservados para gerar dados de teste — consulta [Dados de teste da sandbox](#dados-de-teste-da-sandbox).

**sex** `integer` *required*

Sexo biológico segundo a norma ISO/IEC 5218. Usa `1` para masculino, `2` para feminino. O
laboratório precisa dele para os intervalos de referência, pelo que `0` (desconhecido) devolve
`400`. Obrigatório, exceto se o teu grupo de perfis permitir que o paciente o introduza na página
de ativação do kit. Nesse caso, omite-o. Consulta
[Deixar o paciente introduzir a data de nascimento e o sexo](https://docs.anivahealth.com/pt/concepts/profiles.md#deixar-o-paciente-introduzir-a-data-de-nascimento-e-o-sexo).

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

Data de nascimento no formato `YYYY-MM-DD`. Tem de ser no passado e não anterior a 1900. A idade
implícita tem de estar entre 16 e 100 anos. Outros valores devolvem `400`. Obrigatório, exceto
se o teu grupo de perfis permitir que o paciente a introduza na página de ativação do kit. Nesse
caso, omite-a.

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

Referência polimórfica (UUID ou slug) para o grupo de perfis ao qual atribuir este perfil. O UUID
é o identificador imutável e mantém-se se o slug mudar de nome; o slug continua a ser aceite para
integrações de marketing e de parceiros baseadas em identificadores legíveis. O UUID é preferível.
O grupo de perfis tem de estar dentro do contexto de acesso da tua chave API. Obrigatório, exceto
se enviares o campo obsoleto `profile_group_slug`.

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

Obsoleto: usa `profile_group`. Slug do grupo de perfis. Apenas letras minúsculas, dígitos, hífenes
e underscores.

**email** `string`

Endereço de email do perfil. Se for omitido, a Aniva gera automaticamente um endereço de email.

Fornecer `email` também torna a criação **segura para novas tentativas**: um endereço só pode ter um
perfil, pelo que um pedido repetido devolve `409` em vez de um segundo perfil. Os endereços gerados
automaticamente são únicos por pedido. Envia `email` ou uma `Idempotency-Key` se a tua integração
fizer novas tentativas.

**phone** `string`

Número de telefone no formato E.164 (por exemplo, `+14155552671`).

**height** `number`

Altura em centímetros.

**weight** `number`

Peso em quilogramas.

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

Idioma preferido do perfil: `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` ou `uk`. O valor predefinido é `en`.

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

Indica se este perfil deve receber emails transacionais (programáticos) — confirmações de
marcações, avisos de resultados prontos, etc. Substitui a predefinição do grupo de perfis.
Distinto da autorização de marketing. Omite para usar a predefinição.

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

Indica se este perfil aceita receber emails de marketing (newsletters, novidades de produto).
Substitui a predefinição do grupo de perfis. Distinto dos emails transacionais. Omite para usar
a predefinição do grupo de perfis. Apenas de escrita: não é devolvido na resposta do perfil.

## Dados de teste da sandbox

Todos os caminhos de leitura que vale a pena testar — [Listar marcações](https://docs.anivahealth.com/pt/api/appointments/list-appointments.md),
[Obter resultados](https://docs.anivahealth.com/pt/api/appointments/get-results.md),
[Transferir documento](https://docs.anivahealth.com/pt/api/documents/download-document.md) — estão vazios até acontecer uma colheita de
sangue real dias depois. Isso torna difícil escrever um teste de integração automatizado.

Três valores de `last_name` estão reservados para resolver isso. Cria um perfil com um deles e a
Aniva preenche previamente o estado descrito abaixo antes de responder, para que a tua chamada
seguinte já o veja:

| `last_name` | O que o perfil recebe |
| - | - |
| `Upcomingtestmann` | Uma marcação futura `confirmed` com um painel associado. Ainda sem resultados. |
| `Partialtestmann` | Uma marcação passada `blood_drawn`. Cerca de **metade** do painel está reportada; [Obter resultados](https://docs.anivahealth.com/pt/api/appointments/get-results.md) é `in_progress`. |
| `Fulltestmann` | Uma marcação passada `blood_drawn`. **Todos** os biomarcadores do painel estão reportados, `status: "completed"`, e um PDF do relatório laboratorial em `documents[]`. |

A correspondência não distingue maiúsculas de minúsculas. Todos os outros campos — incluindo
`date_of_birth` e `sex` — são guardados e usados normalmente, pelo que os intervalos de referência
que recebes são os reais, específicos para a idade e o sexo do perfil que criaste.

A marcação fica agendada no local **Aniva Test**, num horário real disponível daqui a pelo menos cinco
dias (ou há cinco dias, para os estados passados). Gerá-la não cria nenhum pedido laboratorial nem marca
estafeta.

> [!NOTE]
>
> Dá aos perfis de teste um endereço que controles. Os lembretes de marcação da Aniva são acionados por
> `scheduled_at`, por isso o cenário futuro vai enviá-los, a menos que o perfil tenha o envio desativado via
> `transactional_emails_enabled: false`.

O painel é escolhido aleatoriamente entre os que a tua chave de API consegue ver, pelo que o seu `panel_id` é sempre resolvido
no teu próprio [Listar painéis](https://docs.anivahealth.com/pt/api/panels/list-panels.md). Os biomarcadores clínicos recebem um valor dentro do
intervalo de referência do biomarcador; os genes recebem um genótipo aleatório dos dados de referência da Aniva, com as variantes, o significado clínico e os rs ids correspondentes a derivarem daí.

> [!NOTE]
>
> O painel e os valores são gerados novamente em cada criação, por isso valida a estrutura em vez de um
> painel específico ou números exatos.

## Resposta

Em caso de sucesso, a API devolve `201 Created` com o perfil recém-criado.

**id** `string` *required*

Identificador único do perfil (UUID).

**handle** `string`

Handle ou nome de utilizador do perfil. Pode ser `null`.

**first\_name** `string`

Nome próprio. Pode ser `null`.

**last\_name** `string`

Apelido. Pode ser `null`.

**email** `string`

Endereço de email. Pode ser `null`.

**phone** `string`

Número de telefone no formato E.164. Pode ser `null`.

**sex** `integer`

Sexo biológico segundo a norma ISO/IEC 5218 (`0` = desconhecido, `1` = masculino, `2` = feminino). Pode ser `null`.

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

Data de nascimento no formato `YYYY-MM-DD`. Pode ser `null`.

**height** `number`

Altura em centímetros. Pode ser `null`.

**weight** `number`

Peso em quilogramas. Pode ser `null`.

**language** `string`

Idioma preferido, um dos 32 códigos acima.

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

Indica se este perfil recebe emails transacionais (programáticos). `null` quando nunca foi definido.

**created\_at** `string`

Carimbo de data/hora ISO 8601 da criação do perfil.

**updated\_at** `string`

Carimbo de data/hora ISO 8601 da última atualização. `null` para perfis recém-criados.

## Respostas de erro

| Estado | Descrição |
| - | - |
| `400` | Erro de validação — um ou mais campos falharam na validação. |
| `403` | Proibido — a tua chave de API não tem acesso a esta operação ou o grupo de perfis está fora do teu contexto de acesso. |
| `404` | Grupo de perfis não encontrado. |
| `409` | Já existe um perfil para o `email` fornecido (a resposta inclui o endereço) ou para a mesma pessoa (vê abaixo), ou a `Idempotency-Key` foi reutilizada com um corpo diferente, ou o pedido original ainda não foi concluído. |
| `500` | Erro interno do servidor. |

Um `409` tem este aspeto — trata-o como "este perfil já existe" e procura-o com
[Listar perfis](https://docs.anivahealth.com/pt/api/profiles/list-profiles.md) (`?email=`) em vez de voltares a tentar a criação:

```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"
}
```

Uma pessoa com o mesmo nome próprio, apelido, sexo e data de nascimento de um perfil que a tua chave consegue ver
recebe um `409` com `error_name: "duplicate_profile_error"`. Usa o `profile_id` devolvido em vez de
criares um segundo perfil:

```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"
}
```

Os apelidos de sandbox que geram dados de teste estão isentos.

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