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

# Créer un rendez-vous

> Planifier un rendez-vous de prise de sang pour un profil dans un lieu de test

Planifie un rendez-vous de prise de sang pour un profil patient dans un lieu de test précis. Une fois créé, le rendez-vous passe au statut `confirmed` par défaut (certains lieux peuvent utiliser `pending` par défaut — c'est un paramètre propre à chaque lieu). Utilise [Ajouter des panels](https://docs.anivahealth.com/fr/api/appointments/add-panels.md) pour associer des panels de bilan sanguin avant de [confirmer la prise de sang](https://docs.anivahealth.com/fr/api/appointments/confirm-blood-draw.md).

> [!NOTE]
>
> Un profil peut détenir au maximum **un** rendez-vous par lieu et par horaire. Créer un
> rendez-vous sur un créneau que le profil occupe déjà renvoie `409` avec l'`appointment_id`
> existant au lieu d'un second rendez-vous — une requête relancée ou répétée par erreur ne peut
> donc jamais créer de doublon. Voir [Rendez-vous en double](#rendez-vous-en-double).

Envoie un en-tête facultatif `Idempotency-Key` pour pouvoir relancer cette création sans risque — répéter la même clé renvoie la réponse d'origine au lieu d'en créer un second. Voir [Idempotence](https://docs.anivahealth.com/fr/concepts/idempotency.md).

Nécessite le scope `appointments_schedule`.

## Requête

### Paramètres du corps

**profile\_id** `string` *required*

UUID du profil patient pour lequel créer le rendez-vous.

**location\_id** `string` *required*

UUID du lieu de test où se déroulera la prise de sang. Utilise [Lister les
lieux](https://docs.anivahealth.com/fr/api/locations/list-locations.md) pour trouver les identifiants des lieux disponibles.

**scheduled\_at** `string` *required*

Date et heure du rendez-vous au format ISO 8601 (par ex. `2026-05-15T10:30:00Z` ou
`2026-05-15T12:30:00+02:00`). **Doit inclure un indicateur de fuseau horaire** — soit `Z`, soit
un décalage explicite comme `+02:00` ; les dates/heures sans fuseau sont rejetées. Doit être dans
le futur.

Doit correspondre exactement au début d'un créneau sur la grille du lieu, et le créneau doit encore
avoir de la disponibilité — consulte d'abord
[Récupérer les disponibilités](https://docs.anivahealth.com/fr/api/locations/get-availability.md). Les horaires hors grille renvoient
`400` ; un créneau complet renvoie `409`. Dans les lieux gérés par Aniva, il doit aussi se situer
au moins 12 heures à l'avance — voir [Délai minimum](#delai-minimum).

**results\_ready\_emails** `string[]`

Jusqu'à 5 adresses qui reçoivent chacune un e-mail dès que tous les résultats de laboratoire sont
définitifs. L'e-mail renvoie vers la page des résultats dans le panneau d'administration Aniva.
Ta clé doit disposer de l'accès `results_view` pour le patient, sinon `403`. Omets ce champ pour
utiliser les adresses par défaut définies pour le groupe du patient. Une liste vide désactive les
e-mails. Voir [E-mails de résultats prêts](https://docs.anivahealth.com/fr/concepts/results.md#e-mails-de-resultats-prets).

**draw\_method** `string`

Méthode de prise de sang : `capillary` ou `venous`. Omets ce champ pour utiliser le
`default_draw_method` du lieu. Le lieu doit inclure cette méthode dans ses `draw_methods`, sinon
`400`.

## Réponse

En cas de succès, l'API renvoie `201 Created` avec le nouveau rendez-vous.

**id** `string` *required*

Identifiant unique du rendez-vous (UUID).

**profile\_id** `string` *required*

UUID du profil auquel ce rendez-vous appartient.

**location\_id** `string`

UUID du lieu de test où la prise de sang a lieu.

**scheduled\_at** `string`

Date et heure prévues du rendez-vous en UTC (ISO 8601 avec suffixe `Z`, par ex.
`2026-05-15T10:30:00Z`). Peut être `null`.

**status** `string` *required*

Statut actuel du rendez-vous. Prend l'une des valeurs `pending`, `confirmed`, `blood_drawn` ou
`cancelled`. Le détail d'avancement des résultats de laboratoire s'obtient via
[Récupérer les résultats](https://docs.anivahealth.com/fr/api/appointments/get-results.md) ; la progression fine des envois via
chaque entrée du tableau `shipments` intégré (voir ci-dessous), puis
[Récupérer un envoi](https://docs.anivahealth.com/fr/api/shipments/get-shipment.md).

**cancellation\_reason** `string`

Motif en texte libre saisi lors de l'annulation du rendez-vous (par ex. absence, annulation tardive,
« Échec. À refaire »). `null` sauf si `status` vaut `cancelled`.

**results\_ready\_emails** `string[]` *required*

Adresses en minuscules qui reçoivent chacune un e-mail une fois tous les résultats de laboratoire
définitifs. Vide si désactivé. Voir [E-mails de résultats prêts](https://docs.anivahealth.com/fr/concepts/results.md#e-mails-de-resultats-prets).

**draw\_method** `string` *required*

Méthode de prise de sang : `capillary` (au bout du doigt ou sur le haut du bras, dans des microtubes) ou `venous` (dans la veine,
dans des tubes). C'est la méthode définie par le rendez-vous, sinon le `default_draw_method` de son
[lieu](https://docs.anivahealth.com/fr/concepts/locations.md). Après la prise de sang, c'est la méthode qui a été utilisée.

**profile** `object` *required*

Le profil patient associé à ce rendez-vous.

**profile**

**id** `string`

Identifiant unique du profil (UUID).

**handle** `string`

Pseudonyme ou nom d'utilisateur du profil. Peut être `null`.

**first\_name** `string`

Prénom. Peut être `null`.

**last\_name** `string`

Nom de famille. Peut être `null`.

**email** `string`

Adresse e-mail. Peut être `null`.

**phone** `string`

Numéro de téléphone au format E.164. Peut être `null`.

**sex** `integer`

Sexe biologique selon la norme ISO/IEC 5218. Peut être `null`.

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

Date de naissance au format `YYYY-MM-DD`. Peut être `null`.

**height** `number`

Taille en centimètres. Peut être `null`.

**weight** `number`

Poids en kilogrammes. Peut être `null`.

**language** `string`

Langue préférée : l'un des 32 codes dans [Créer un profil](https://docs.anivahealth.com/fr/api/profiles/create-profile.md).

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

Indique si ce profil reçoit des e-mails transactionnels (programmatiques). Peut être `null`.

**panels** `AppointmentPanel[]` *required*

Panels actuellement associés à ce rendez-vous. Vide pour les rendez-vous nouvellement créés —
associe-les via [Ajouter des panels](https://docs.anivahealth.com/fr/api/appointments/add-panels.md). Consulte le détail des panels
(nom, biomarqueurs) via [Lister les panels](https://docs.anivahealth.com/fr/api/panels/list-panels.md).

**Champs de rattachement de panel**

**panel\_id** `string`

UUID du panel — à croiser avec [Lister les panels](https://docs.anivahealth.com/fr/api/panels/list-panels.md).

**added\_at** `string`

Horodatage ISO 8601 auquel le panel a été rattaché pour la première fois à ce rendez-vous.

**individual\_biomarkers** `AppointmentIndividualBiomarker[]` *required*

Biomarqueurs à la carte associés à ce rendez-vous en dehors de tout panel. Vide pour les
rendez-vous nouvellement créés — associe-les via
[Ajouter des biomarqueurs individuels](https://docs.anivahealth.com/fr/api/appointments/add-individual-biomarkers.md). Croise chaque
`biomarker_id` avec [Lister les biomarqueurs](https://docs.anivahealth.com/fr/api/biomarkers/list-biomarkers.md) pour obtenir les
données d'affichage.

**Champs de biomarqueur individuel**

**biomarker\_id** `integer`

Identifiant du biomarqueur — à croiser avec
[Lister les biomarqueurs](https://docs.anivahealth.com/fr/api/biomarkers/list-biomarkers.md).

**added\_at** `string`

Horodatage ISO 8601 auquel le biomarqueur a été rattaché pour la première fois à ce rendez-vous.

**shipments** `AppointmentShipmentLink[]` *required*

Envois liés à ce rendez-vous, du lien le plus ancien au plus récent. Vide pour les rendez-vous
nouvellement créés — lie-les via [Créer un envoi](https://docs.anivahealth.com/fr/api/shipments/create-shipment.md) (avec
`appointment_id`) ou [Associer des rendez-vous à un
envoi](https://docs.anivahealth.com/fr/api/shipments/attach-appointments-to-shipment.md).

**Champs de lien d'expédition**

**id** `string`

Identifiant de référence de l'expédition — à croiser avec
[Obtenir une expédition](https://docs.anivahealth.com/fr/api/shipments/get-shipment.md).

**added\_at** `string`

Horodatage ISO 8601 auquel l'expédition a été liée pour la première fois à ce rendez-vous.

**lab\_codes** `string[]` *required*

Codes laboratoire (codes-barres des tubes) enregistrés pour ce rendez-vous, dans l'ordre de scan. Vide jusqu'à
la confirmation de la prise de sang. Une prise de sang veineuse porte un seul code imprimé sur chaque tube ; une prise de sang capillaire porte un
code par microtube. Les résultats et documents dans [Obtenir les résultats](https://docs.anivahealth.com/fr/api/appointments/get-results.md) référencent
ces codes via `lab_code`.

## Délai minimum

Les rendez-vous dans les lieux gérés par Aniva doivent être réservés au moins **12 heures** à
l'avance ; toute réservation dans ce délai renvoie `400`.
[Récupérer les disponibilités](https://docs.anivahealth.com/fr/api/locations/get-availability.md) masque déjà ces créneaux, donc tout
ce qui apparaît sur cette grille est réservable.

Les lieux que tu gères toi-même n'ont aucun délai minimum — la réservation le jour même et sans rendez-vous reste inchangée.

## Rendez-vous en double

Un profil peut détenir au maximum un rendez-vous non annulé par lieu et par horaire — une personne
ne peut pas faire deux prises de sang au même endroit au même moment, quel que soit le nombre de
fauteuils du lieu.

Créer un rendez-vous sur un créneau que le profil occupe déjà renvoie `409` avec un
`appointment_id` indiquant le rendez-vous qui existe déjà :

```json theme={null}
{
  "error": "This profile already has an appointment at this location and time. Reschedule or cancel the existing appointment instead of creating a second one.",
  "appointment_id": "03e916d2-7fd6-4414-8276-8532a105edc3"
}
```

Gère ce cas en considérant la requête comme déjà appliquée : récupère le rendez-vous avec
[Récupérer un rendez-vous](https://docs.anivahealth.com/fr/api/appointments/get-appointment.md), déplace-le avec
[Mettre à jour un rendez-vous](https://docs.anivahealth.com/fr/api/appointments/update-appointment.md) ou supprime-le avec
[Annuler un rendez-vous](https://docs.anivahealth.com/fr/api/appointments/cancel-appointment.md). Ne relance pas la création — elle
continuera de renvoyer `409`.

Cela rend les créations répétées sans risque : une requête que tu renvoies après un délai
d'expiration, ou un formulaire soumis deux fois, ne peut pas produire deux rendez-vous pour le même
patient au même moment.

> [!NOTE]
>
> `appointment_id` n'est présent que sur le `409` de doublon. Le `409` de capacité — le créneau est
> complet parce que d'*autres* patients l'occupent — renvoie `error` seul, et la bonne démarche
> consiste alors à choisir un autre créneau dans
> [Récupérer les disponibilités](https://docs.anivahealth.com/fr/api/locations/get-availability.md).

## Réponses d'erreur

| Statut | Description |
| - | - |
| `400` | Erreur de validation — par exemple, `scheduled_at` est dans le passé, est à moins de 12 heures dans un lieu géré par Aniva, ne correspond pas au début exact d'un créneau du planning du lieu, ou le lieu n'a pas de contenants en stock pour `draw_method`. |
| `403` | Accès refusé — ta clé API n'a pas accès à cette opération, ou `results_ready_emails` est défini sans accès `results_view` au patient. |
| `404` | Profil ou lieu introuvable, ou le lieu est inactif. |
| `409` | Ce profil a déjà un rendez-vous à ce lieu et à cette heure (contient `appointment_id`), le créneau est complet, le lieu est fermé à cette date, ou `Idempotency-Key` a été réutilisée avec un corps différent, ou sa requête d'origine n'est pas terminée. |
| `500` | Erreur interne du serveur. |

```bash cURL theme={null}
curl --request POST \
  --url https://anivahealth.com/api/v1/appointments \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
    "location_id": "b7e2d1f5-3c4a-4e8b-a2f1-9d0c1e2f3a4b",
    "scheduled_at": "2026-05-15T10:30:00Z"
  }'
```

```json 201 theme={null}
{
  "id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
  "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
  "location_id": "b7e2d1f5-3c4a-4e8b-a2f1-9d0c1e2f3a4b",
  "scheduled_at": "2026-05-15T10:30:00Z",
  "status": "confirmed",
  "cancellation_reason": null,
  "results_ready_emails": [],
  "draw_method": "venous",
  "created_at": "2026-04-01T09:45:00Z",
  "updated_at": null,
  "profile": {
    "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
  },
  "panels": [],
  "individual_biomarkers": [],
  "shipments": [],
  "lab_codes": []
}
```

```json 400 theme={null}
{
  "error": "Appointments must be booked at least 12 hours in advance. Please pick a later time."
}
```

```json 404 theme={null}
{
  "error": "Location not found or inactive"
}
```

```json 409 theme={null}
{
  "error": "This profile already has an appointment at this location and time. Reschedule or cancel the existing appointment instead of creating a second one.",
  "appointment_id": "03e916d2-7fd6-4414-8276-8532a105edc3"
}
```


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