> ## Documentation Index
> Fetch the complete documentation index at: https://developers.avest.fr/llms.txt
> Use this file to discover all available pages before exploring further.

# Consentement à la prospection

> Transmettre le consentement d'un contact à la création et à la mise à jour : canaux, parcours déclaré, durées et traçabilité.

Un contact Avest porte un consentement **par canal de prospection** : `email`, `phone`, `sms`. L'API vous permet de transmettre le consentement que **vous** avez recueilli, avec sa date et la mention affichée à la personne.

> [!WARNING]
>
> **Vous êtes responsable de ce que vous transmettez.** Ne déclarez un canal
> consenti que si la personne a bien vu une mention l'annonçant. Sans objet
> `consent`, Avest enregistre un contact **sans aucun consentement** — c'est le
> comportement sûr par défaut.

## L'objet `consent`

Accepté sur `POST /external-integration/contact` et `PATCH /external-integration/contact/{contactId}`.

| Champ | Type | Description |
| - | - | - |
| `email` | Boolean | Consentement à la prospection par courriel. |
| `phone` | Boolean | Consentement à la prospection téléphonique. |
| `sms` | Boolean | Consentement à la prospection par SMS. |
| `journey` | String | Parcours déclaré : `sale`, `rental` ou `acquisition`. **Création uniquement.** |
| `date` | String | Date de recueil, ISO 8601. **Obligatoire dès qu'un canal est consenti.** Ne peut pas être dans le futur. |
| `wordingText` | String | Texte exact de la mention affichée à la personne. 1 à 5000 caractères. **Obligatoire si `phone` est consenti.** |
| `wordingVersion` | String | Version de cette mention, selon votre propre référence. 1 à 64 caractères. **Obligatoire si `phone` est consenti.** |
| `locale` | String | Langue de la mention (ex. `fr`). 2 à 10 caractères. **Obligatoire si `phone` est consenti.** |
| `details` | String | Contexte du recueil, conservé dans le journal d'audit. 1000 caractères max. |
| `durationYears` | Number | Durée du consentement courriel/SMS, en années. Entier de 1 à 3. |
| `retentionDurationYears` | Number | Durée de conservation de la donnée, en années. Entier de 1 à 20 (au-delà : `400`). Ne peut que **raccourcir** la durée réglée par l'agence (3 ans si l'agence n'a rien réglé, 10 ans au plus) : une valeur supérieure est ramenée à cette durée, sans erreur. |

Ce qu'un canal **absent** de l'objet devient dépend de la route :

* `PATCH` : il n'est **pas modifié**. Envoyez `false` pour retirer un consentement.
* `POST` avec un `journey` : il n'est **pas modifié** s'il n'est pas annoncé par ce parcours.
* `POST` sans `journey` : sur un **nouveau** contact, il est enregistré comme **non consenti**. Sur un contact **déjà connu** d'Avest (dédup), il n'est **pas modifié** : seul un `false` explicite retire un consentement qu'il portait.

## Date et mention obligatoires

Un canal est **consenti** quand il vaut `true`, ou quand le `journey` déclaré l'annonce sans que vous l'ayez mis à `false`.

* **`date`** est obligatoire dès qu'au moins un canal est consenti. Un `consent` qui ne fait que retirer des canaux (`false`) n'en demande pas.
* **`wordingText`, `wordingVersion` et `locale`** sont obligatoires dès que `phone` est consenti. Les trois parcours annoncent le téléphone : avec un `journey`, ils sont donc requis, sauf si vous envoyez `"phone": false`. Pour le courriel et le SMS seuls, ils restent facultatifs, mais sont contrôlés s'ils sont transmis.

Sinon, la requête est rejetée en `400` et rien n'est écrit : ni le contact (`POST`), ni ses modifications (`PATCH`).

## Déclarer un parcours plutôt que lister les canaux

`journey` indique **quelle mention la personne a vue**. Les canaux que ce formulaire annonce deviennent consentis, sans avoir à les énumérer :

| `journey` | `email` | `phone` | `sms` |
| - | - | - | - |
| `sale` | ✅ | ✅ | ✅ |
| `rental` | ✅ | ✅ | ✅ |
| `acquisition` | ✅ | ✅ | ✅ |

Les trois parcours annoncent les trois canaux. Un canal que le parcours n'annonce pas n'est **pas** écrit comme un refus : il est laissé intact.

Les booléens par canal restent prioritaires : `{ "journey": "acquisition", "sms": false }` consent au courriel et au téléphone, et refuse le SMS.

> [!NOTE]
>
> `journey` n'est accepté qu'à la **création**. Sur `PATCH`, la requête est
> rejetée : une mise à jour énonce chaque canal explicitement.

## Durées

* **Téléphone : un an**, fixé par la réglementation, sans reconduction tacite. `durationYears` ne s'y applique pas.
* **Courriel et SMS : trois ans** par défaut, ou la valeur de `durationYears` si vous la transmettez, à la création (`POST`) comme à la mise à jour (`PATCH`). Le réglage de durée de l'agence ne s'applique pas à un consentement transmis par l'API.
* `durationYears` est un entier de 1 à 3 : c'est la plage acceptée par l'API. Toute autre valeur est **rejetée** (`400`) plutôt que silencieusement raccourcie : mieux vaut une erreur qu'un `200` cachant un consentement plus court que celui annoncé à la personne.
* L'expiration du consentement se calcule à partir de `date`, pas de l'instant de l'appel.
* La fin de conservation du contact se calcule à partir de son accord le plus récent, tous canaux confondus (sa `date` de recueil, et non l'instant de l'appel), plus la durée de conservation appliquée (voir `retentionDurationYears`). Un recueil ancien donne donc une fin de conservation proche, voire déjà passée. Un accord ignoré parce que déjà enregistré ne la prolonge pas.

## Traçabilité

Chaque consentement pris en compte crée une entrée dans le journal d'audit du contact, avec sa source, sa date de recueil, la mention affichée (`wordingText`, `wordingVersion`, `locale`) et le contexte (`details`). Un canal ignoré parce que déjà enregistré n'y figure pas.

> [!WARNING]
>
> Ne transmettez `true` que pour un **nouvel accord** de la personne, daté
> dans `date`. Ne renvoyez pas, lors d'une resynchronisation, un consentement
> déjà transmis.
>
> Sur un canal **encore consenti**, un `true` n'est enregistré que si sa `date`
> est **postérieure** au recueil déjà enregistré. Sinon il est ignoré et ne
> prolonge ni le consentement ni la durée de conservation.
>
> Sur un canal **retiré depuis** (désinscription, retrait par l'agence, `false`
> transmis), un `true` transmis **rétablit le consentement**, y compris le
> renvoi d'un accord déjà transmis. N'envoyez donc `true` sur un canal retiré
> que pour un nouvel accord, donné par la personne après son retrait.

Un renvoi ignoré, comme le retrait d'un canal déjà retiré, n'écrit rien : si aucun autre canal ne change, `PATCH` renvoie `consentChanged: false`.

Un retrait du courriel arrête les séquences marketing du contact et l'exclut des campagnes courriel. Un retrait du SMS l'exclut des campagnes SMS. Un retrait ne coupe pas les messages liés à une transaction en cours, et les appels restent à l'initiative de l'agence, qui voit le retrait sur la fiche du contact.

Une opposition RGPD déjà enregistrée sur le contact **survit** à un consentement transmis par l'API : elle n'est jamais levée par cette route.

## Exemples

Un partenaire qui a affiché la mention du formulaire acquéreur :

```json theme={null}
{
  "agencyId": "66cc91d475c9fac35c86ed80",
  "firstName": "Jean",
  "email": "jean.dupont@email.com",
  "consent": {
    "journey": "acquisition",
    "date": "2026-08-01T09:30:00.000Z",
    "wordingText": "J'accepte d'être contacté par l'agence par courriel, téléphone et SMS au sujet de mon projet immobilier.",
    "wordingVersion": "acquereur-v2",
    "locale": "fr",
    "details": "Case cochée sur le formulaire acquéreur du site partenaire"
  }
}
```

Un recueil canal par canal, sans le téléphone et avec une durée plus courte — la mention n'est alors pas obligatoire :

```json theme={null}
{
  "agencyId": "66cc91d475c9fac35c86ed80",
  "firstName": "Jean",
  "email": "jean.dupont@email.com",
  "consent": {
    "email": true,
    "phone": false,
    "sms": true,
    "date": "2026-08-01T09:30:00.000Z",
    "durationYears": 1
  }
}
```

## Erreurs

| Message | Cause |
| - | - |
| `consent.email must be a boolean` | Un canal reçoit autre chose qu'un booléen. |
| `consent.journey must be one of sale, rental, acquisition` | Parcours inconnu. |
| `consent.journey is only supported on contact creation` | `journey` envoyé sur `PATCH`. |
| `consent.date must be an ISO 8601 date string` | Date illisible. |
| `consent.date cannot be in the future` | Date de recueil postérieure à maintenant. |
| `consent.date is required when a channel is granted` | Un canal est consenti (`true` ou `journey`) sans `date`. |
| `consent.wordingText is required when phone is granted` | `phone` est consenti sans `wordingText`. Même message pour `wordingVersion` et `locale`. |
| `consent.wordingText must be a string of 1 to 5000 characters` | `wordingText` vide ou trop long. Bornes : `wordingVersion` 1 à 64, `locale` 2 à 10. |
| `consent.details must be a non-empty string` | `details` vide ou d'un autre type. |
| `consent.durationYears must be an integer between 1 and 3` | Durée hors de la plage acceptée par l'API : un entier de 1 à 3 ans pour le courriel et le SMS. |
| `consent.retentionDurationYears must be an integer between 1 and 20` | Durée de conservation hors bornes. |

L'API préfixe ces messages du nom de la route, par exemple `ExternalIntegrationCreateContact : consent.date is required when a channel is granted`.


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