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

# POST Contact

> Crée un contact seul. À n'utiliser qu'en dernier recours : privilégiez la création du contact AVEC sa transaction.

Crée un **contact seul** dans une agence de votre périmètre.

> [!WARNING]
>
> **À éviter dans le cas général.** Pour démarrer une affaire (vente,
> acquisition, location), créez le contact **en même temps que la transaction**
> via `POST /external-integration/sale`, `…/acquisition` ou `…/rental` (bloc
> `contact`). Ces routes appliquent la **déduplication** ET l'**allocation
> automatique** d'agence / collaborateur.
>
> **Ne créez JAMAIS un contact via cette route puis une transaction
> séparément** : vous contournez la déduplication et l'allocation, et vous
> créez des doublons. Cette route n'existe que pour les cas où vous devez créer
> un contact **sans** transaction associée.

## Endpoint

**URL** : `/external-integration/contact`
**Méthode** : `POST`
**Authentification** : Requiert un token LinkedAPI avec scope `externalIntegration` et une clé rattachée à un groupe d'agences.
**Clé requise** : lecture-écriture. Une clé en lecture seule reçoit `403`. Voir [Types de clé](https://developers.avest.fr/guides/authentification.md).

> [!NOTE]
>
> Un `GET /external-integration/contact` existe aussi (récupérer un contact). La
> création utilise la même URL en `POST`.

## Headers

```
Content-Type: application/json
Authorization: Bearer {token}
```

## Body Parameters

| Champ | Type | Requis | Description |
| - | - | - | - |
| `agencyId` | ObjectId | ✅ | Agence cible. Doit appartenir au périmètre autorisé de la clé. |
| `firstName` | String | ⚠️ | Prénom. Requis (avec ou à la place de `lastName`) si contact particulier. |
| `lastName` | String | ⚠️ | Nom. Requis (avec ou à la place de `firstName`) si contact particulier. |
| `email` | String | ⚠️ | Email. **Au moins un** de `email` / `phone` est requis. |
| `phone` | String | ⚠️ | Téléphone (format international). **Au moins un** de `email` / `phone`. |
| `isEmailVerified` | Boolean | ❌ | Marque l'email comme vérifié. |
| `isPhoneVerified` | Boolean | ❌ | Marque le téléphone comme vérifié. |
| `isIndividual` | Boolean | ❌ | `true` (défaut) = particulier ; `false` = entreprise. |
| `commercialName` | String | ⚠️ | Nom commercial. Requis si `isIndividual: false` (avec/à la place de `corporateName`). |
| `corporateName` | String | ⚠️ | Raison sociale. Requis si `isIndividual: false`. |
| `consent` | Object | ❌ | Consentement recueilli par vos soins. Voir [Consentement](https://developers.avest.fr/guides/consentement.md). |

## Consentement

Sans objet `consent`, le contact est créé **sans aucun consentement de prospection** — c'est le comportement par défaut.

Vous pouvez soit déclarer le parcours dont la personne a vu la mention (`consent.journey` = `sale`, `rental` ou `acquisition`), soit énoncer chaque canal (`email`, `phone`, `sms`). Dès qu'un canal est consenti, `consent.date` est obligatoire ; dès que le téléphone l'est — c'est le cas des trois parcours, sauf `"phone": false` —, la mention affichée l'est aussi (`wordingText`, `wordingVersion`, `locale`). Détail des durées, de la date de recueil et de la traçabilité : [Consentement à la prospection](https://developers.avest.fr/guides/consentement.md).

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

> [!NOTE]
>
> Sur un contact déjà existant (dédup), un `consent` transmis est **quand même
> appliqué** : Avest l'enregistre comme le recueil que vous déclarez, et non
> comme une valeur par défaut. Seuls les canaux que vous citez sont écrits : un
> canal absent de l'objet (sans `journey`) garde son état, et seul un `false`
> explicite retire un consentement. Un canal que la fiche porte déjà consenti
> n'est renouvelé que si votre `date` est strictement postérieure à l'accord
> enregistré. Sinon il est ignoré, sans erreur, et la réponse (`201`) ne le
> signale pas. Sur un canal retiré depuis, le même accord le rétablit.

## Déduplication

Si un contact existe déjà dans l'agence avec le même téléphone/email, il est **réutilisé** (pas de doublon) et retourné avec `isNew: false`. Sinon il est créé (`isNew: true`).

## Exemple de requête

```json theme={null}
{
  "agencyId": "66cc91d475c9fac35c86ed80",
  "firstName": "Jean",
  "lastName": "Dupont",
  "email": "jean.dupont@email.com",
  "phone": "+33612345678"
}
```

## Réponse de succès

**Code** : `201`

```json theme={null}
{
  "success": true,
  "contact": {
    "id": "618a35a36d932054e195ca0a",
    "firstName": "Jean",
    "lastName": "Dupont",
    "contactDetails": [
      { "type": "phone", "data": "+33612345678" },
      { "type": "email", "data": "jean.dupont@email.com" }
    ]
  },
  "isNew": true
}
```

## Réponses d'erreur

* **`agencyId` manquant** : `400 Bad Request`

```json theme={null}
{
  "success": false,
  "message": "ExternalIntegrationCreateContact : agencyId is required"
}
```

* **`agencyId` hors périmètre** : `400 Bad Request`

```json theme={null}
{
  "success": false,
  "message": "ExternalIntegrationCreateContact : agencyId is not in the authorized scope of this LinkedAPI"
}
```

* **Ni email ni téléphone** : `400 Bad Request`

```json theme={null}
{
  "success": false,
  "message": "ExternalIntegrationCreateContact : At least one of email or phone is required"
}
```

* **Consentement invalide** : `400 Bad Request` — le contact n'est pas créé. Messages détaillés dans le guide [Consentement](https://developers.avest.fr/guides/consentement.md).

```json theme={null}
{
  "success": false,
  "message": "ExternalIntegrationCreateContact : consent.journey must be one of sale, rental, acquisition"
}
```

* **Header `Authorization` absent, clé en lecture seule, ou IP non whitelistée sur une clé sécurisée** : `403 Not authorized to access this resource`

```json theme={null}
{
  "success": false,
  "message": "Not authorized to access this resource"
}
```

* **Token invalide** : `401 Invalid bearer token`

```json theme={null}
{
  "success": false,
  "message": "Invalid bearer token"
}
```

## Rate limits

Cette route est limitée à **100 req / minute par groupe d'agences** (un compteur par groupe d'agences × route : les autres routes d'écriture ont chacune le leur).

* Headers : `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`.
* Dépassement → `429 Too Many Requests` avec header `Retry-After`.


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