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

# Crear perfil

> Crear un nuevo perfil de paciente y asignarlo a un grupo de perfiles

Crea un nuevo perfil de paciente y asígnalo a un grupo de perfiles. El perfil guarda los datos demográficos usados en citas y pedidos de laboratorio.

Requiere el scope `create_user`.

Envía una cabecera opcional `Idempotency-Key` para que esta creación se pueda reintentar con seguridad: repetir la misma clave devuelve la respuesta original en lugar de crear otra. Consulta [Idempotencia](https://docs.anivahealth.com/es/concepts/idempotency.md).

## Solicitud

### Parámetros del cuerpo

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

Nombre del paciente. Debe usar caracteres latinos y tener entre 1 y 100 caracteres.

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

Apellido del paciente. Debe usar caracteres latinos y tener entre 1 y 100 caracteres. Los laboratorios rechazan
pedidos de pacientes sin apellido, por lo que no se puede crear un perfil sin uno.

Hay tres valores reservados para generar datos de prueba; consulta [Datos de prueba en sandbox](#datos-de-prueba-en-sandbox).

**sex** `integer` *required*

Sexo biológico según ISO/IEC 5218. Usa `1` para masculino y `2` para femenino. El laboratorio lo necesita para los
intervalos de referencia, por lo que `0` (desconocido) devuelve `400`. Obligatorio, salvo que tu grupo de perfiles permita al
paciente introducirlo en la página de activación del kit. En ese caso, omítelo. Consulta
[Dejar que el paciente introduzca fecha de nacimiento y sexo](https://docs.anivahealth.com/es/concepts/profiles.md#permitir-que-el-paciente-introduzca-la-fecha-de-nacimiento-y-el-sexo).

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

Fecha de nacimiento en formato `YYYY-MM-DD`. Debe ser anterior a hoy y no anterior a 1900. La edad resultante
debe estar entre 16 y 100 años. Otros valores devuelven `400`. Obligatorio, salvo que tu grupo de perfiles permita
al paciente introducirla en la página de activación del kit. En ese caso, omítelo.

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

Referencia polimórfica (UUID o slug) al grupo de perfiles al que se asigna este perfil. El UUID es
el identificador inmutable y no cambia si se renombra el slug; el slug sigue aceptándose para integraciones de marketing y
de socios basadas en identificadores legibles. Se recomienda usar el UUID. El grupo de perfiles debe estar
dentro del contexto de acceso de tu clave de API. Obligatorio salvo que envíes el campo obsoleto
`profile_group_slug`.

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

Obsoleto: usa `profile_group`. Slug del grupo de perfiles. Solo letras minúsculas, dígitos, guiones y
guiones bajos.

**email** `string`

Dirección de correo electrónico del perfil. Si se omite, Aniva genera una automáticamente.

Proporcionar `email` también hace que la creación sea **segura ante reintentos**: una dirección solo puede tener un perfil, así que
una solicitud repetida devuelve `409` en lugar de crear un segundo perfil. Las direcciones autogeneradas son únicas por
solicitud. Envía `email` o un `Idempotency-Key` si tu integración hace reintentos.

**phone** `string`

Número de teléfono en formato E.164 (p. ej., `+14155552671`).

**height** `number`

Altura en centímetros.

**weight** `number`

Peso en kilogramos.

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

Idioma preferido para el 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` o `uk`. El valor predeterminado es `en`.

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

Si este perfil debe recibir correos transaccionales (automáticos): confirmaciones de cita,
avisos de resultados disponibles, etc. Sobrescribe el valor por defecto del grupo de perfiles. Es independiente
del consentimiento de marketing. Omítelo para usar el valor por defecto.

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

Si este perfil acepta recibir correos de marketing (boletines, novedades de producto). Sobrescribe el
valor por defecto del grupo de perfiles. Es independiente de los correos transaccionales. Omítelo para usar el valor por defecto del grupo de perfiles.
Solo de escritura: no se devuelve en la respuesta del perfil.

## Datos de prueba en sandbox

Todas las rutas de lectura que merece la pena probar —[Listar citas](https://docs.anivahealth.com/es/api/appointments/list-appointments.md),
[Obtener resultados](https://docs.anivahealth.com/es/api/appointments/get-results.md),
[Descargar documento](https://docs.anivahealth.com/es/api/documents/download-document.md)— están vacías hasta que se realiza una extracción de sangre real
días después. Eso dificulta escribir una prueba de integración automatizada.

Hay tres valores de `last_name` reservados para resolverlo. Crea un perfil con uno de ellos y Aniva
precargará el estado descrito abajo antes de responder, para que tu siguiente llamada ya lo vea:

| `last_name` | Qué recibe el perfil |
| - | - |
| `Upcomingtestmann` | Una próxima cita `confirmed` con un panel asociado. Aún sin resultados. |
| `Partialtestmann` | Una cita pasada `blood_drawn`. Aproximadamente la **mitad** del panel tiene resultados; [Obtener resultados](https://docs.anivahealth.com/es/api/appointments/get-results.md) está en `in_progress`. |
| `Fulltestmann` | Una cita pasada `blood_drawn`. **Todos** los biomarcadores del panel tienen resultados, `status: "completed"`, y hay un PDF de informe de laboratorio en `documents[]`. |

La coincidencia no distingue entre mayúsculas y minúsculas. Todos los demás campos —incluidos `date_of_birth` y `sex`— se guardan y
se usan con normalidad, así que los intervalos de referencia que recibes son los reales según la edad y el sexo del
perfil que has creado.

La cita se reserva en la ubicación **Aniva Test**, en una franja real reservable dentro de al menos cinco días
(o hace cinco días, para los estados pasados). Al generarla no se crea ningún pedido de laboratorio ni se reserva ningún
mensajero.

> [!NOTE]
>
> Asigna a los perfiles de prueba una dirección que controles. Los recordatorios de cita de Aniva se rigen por
> `scheduled_at`, así que el caso de prueba próximo los enviará a menos que se desactiven en el perfil mediante
> `transactional_emails_enabled: false`.

El panel se elige al azar entre los que puede ver tu clave de API, así que su `panel_id` siempre aparece
en tu propio [Listar paneles](https://docs.anivahealth.com/es/api/panels/list-panels.md). Los biomarcadores clínicos reciben un valor dentro del
intervalo de referencia del biomarcador; los genes reciben un genotipo aleatorio de los datos de referencia de Aniva, junto con las variantes, la significación clínica y los ID rs que se derivan de él.

> [!NOTE]
>
> El panel y los valores se regeneran en cada creación, así que comprueba la estructura en lugar de un
> panel concreto o números exactos.

## Respuesta

Si tiene éxito, la API devuelve `201 Created` con el perfil recién creado.

**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, uno de los 32 códigos anteriores.

**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. `null` en perfiles recién creados.

## Respuestas de error

| Estado | Descripción |
| - | - |
| `400` | Error de validación: uno o más campos no superaron la validación. |
| `403` | Prohibido: tu clave de API no tiene acceso a esta operación o el grupo de perfiles está fuera de tu contexto de acceso. |
| `404` | Grupo de perfiles no encontrado. |
| `409` | Ya existe un perfil para el `email` proporcionado (la respuesta incluye la dirección), o para la misma persona (consulta más abajo), o se reutilizó `Idempotency-Key` con un cuerpo diferente, o su solicitud original aún no ha terminado. |
| `500` | Error interno del servidor. |

Un `409` tiene este aspecto: trátalo como "este perfil ya existe" y búscalo con
[Listar perfiles](https://docs.anivahealth.com/es/api/profiles/list-profiles.md) (`?email=`) en lugar de reintentar la creación:

```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 el mismo nombre, apellidos, sexo y fecha de nacimiento que un perfil que puede ver tu clave
recibe un `409` con `error_name: "duplicate_profile_error"`. Usa el `profile_id` devuelto en lugar de
crear un 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"
}
```

Los apellidos de sandbox que generan datos de prueba están exentos.

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