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

# Réception de leads (API)

> Faire livrer vos leads achetés directement dans Assurevo : adresse d'ingestion, champs attendus, réponses et erreurs.

Si vous achetez des leads à un fournisseur, à une régie publicitaire ou à un
centre d'appel, ils peuvent arriver **directement dans votre CRM**, sans
ressaisie et sans export. Chaque lead reçu crée ou complète une fiche contact,
et vous alerte immédiatement.

Vous récupérez une adresse dans **Intégrations → Réception de leads**, vous la transmettez à votre
fournisseur, il l'appelle à chaque lead vendu. Dans l'autre sens, Assurevo peut
le prévenir quand un lead qu'il vous a vendu donne un devis puis un contrat
signé : voir « Le retour d'information » plus bas. Cette page est écrite pour
être lue par son équipe technique : **envoyez-lui simplement ce lien**.

## Avant de commencer

**1. Être titulaire du cabinet**

Dans **Intégrations**, cliquez sur **Configurer la réception**, dans l’encadré
**Réception de leads**. Ce réglage est réservé au courtier du cabinet.
Les cartes **Zapier**, **Make** et **Autre outil** ouvrent aussi le même écran.
C'est lui qui active la réception et désigne le responsable des leads
entrants.

**2. Récupérer votre adresse d'ingestion**

Dans **Intégrations → Réception de leads**, copiez le champ **URL de réception (webhook)**. L’adresse
contient un jeton propre à votre cabinet :

```
https://api.assurevo.fr/api/intake/VOTRE_TOKEN
```

**3. Activer la réception et choisir le responsable**

Activez **Activer la réception de leads** avant le premier envoi. L’URL et
le token restent consultables quand la réception est désactivée, mais les
envois sont alors refusés avec un code 404.

Choisissez le membre de l'équipe à qui les contacts entrants sont attribués
et qui reçoit les alertes. Sans choix explicite, ils reviennent au courtier.

> [!WARNING]
>
> **Le jeton est un secret, au même titre qu'un mot de passe.** Toute personne
> qui le détient peut créer des contacts dans votre cabinet. Ne le publiez pas,
> ne le laissez pas traîner dans un tableur partagé. Vous pouvez le régénérer à
> tout moment depuis le même écran : l'ancien cesse aussitôt de fonctionner.

## L'appel

```
POST https://api.assurevo.fr/api/intake/{TOKEN}
Content-Type: application/json
```

Le jeton constitue à lui seul l'authentification. Il n'y a ni clé d'API
supplémentaire, ni en-tête d’authentification, ni signature à calculer.
Le champ **Token du cabinet** permet de le consulter ou de le copier séparément,
mais il est **déjà inclus dans l’URL de réception**. N’utilisez pas votre token
de connexion au CRM et ne renseignez pas d’en-tête `Authorization: Bearer`.

Pour brancher votre outil : méthode **POST**, corps **JSON**, authentification
**Aucune**, en-tête `Content-Type: application/json`. Dans Make, utilisez le
module HTTP avec ces mêmes réglages.

```bash theme={null}
curl -X POST "https://api.assurevo.fr/api/intake/VOTRE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jean.dupont@exemple.fr",
    "phone": "+33612345678",
    "civility": "m",
    "firstName": "Jean",
    "lastName": "Dupont",
    "source": "Oceads",
    "mainNeed": "sante",
    "product": "Mutuelle senior",
    "message": "Souhaite être rappelé le matin.",
    "birthDate": "1968-04-12",
    "profession": "Artisan boulanger",
    "socialRegime": "tns",
    "postalCode": "33000",
    "city": "Bordeaux",
    "currentlyInsured": true,
    "currentInsurer": "Alptis",
    "currentPremium": 89.5,
    "meta": {
      "campaign": "mutuelle-senior-q3",
      "externalId": "LEAD-88213",
      "price": 42
    }
  }'
```

> [!WARNING]
>
> **Un dépôt réussi répond `201 Created`, pas `200 OK`.**
>
> Si votre plateforme ne considère que `200` comme un succès, elle lira chaque
> livraison réussie comme un échec et rejouera des leads déjà enregistrés.
> Configurez la validation sur **`2xx`**, ou sur `201`.

## Les champs

Le corps est un objet JSON. Les champs du tableau ci-dessous sont validés et
renseignent la fiche. **Tout autre champ envoyé est conservé** et affiché tel
quel dans l'encadré « Lead reçu » de la fiche du contact, sous son propre nom :
c'est ainsi qu'un formulaire relayé par Zapier arrive entier, question par
question. `meta` reste la place des références techniques (campagne,
identifiant interne, prix du lead), qui sont affichées à part.

| Champ | Type | Max | Remarques |
| - | - | - | - |
| `email` | chaîne | format email | Sert aussi de clé de rapprochement |
| `phone` | chaîne | 40 | Normalisé au format international lorsque possible (ex. `0612345678` devient `+33612345678`) ; sinon conservé après suppression des espaces en début et fin |
| `firstName` | chaîne | 100 | |
| `lastName` | chaîne | 100 | |
| `fullName` | chaîne | 200 | Utilisé seulement si `firstName` et `lastName` sont absents. Coupé au premier espace |
| `civility` | chaîne | 10 | `m`, `mme` ou `mlle` |
| `source` | chaîne | 40 | Voir plus bas |
| `mainNeed` | chaîne | 60 | Voir plus bas |
| `product` | chaîne | 120 | Nom commercial. Permet de distinguer deux opportunités sur un même contact |
| `message` | chaîne | 2000 | Commentaire libre, affiché sur la fiche |
| `birthDate` | chaîne | 30 | `AAAA-MM-JJ` ou `JJ/MM/AAAA`. Hors format, le champ est ignoré |
| `profession` | chaîne | 100 | |
| `socialRegime` | chaîne | 60 | Régime obligatoire déclaré. Voir plus bas |
| `address` | chaîne | 200 | Adresse du domicile |
| `postalCode` | chaîne | 10 | |
| `city` | chaîne | 100 | |
| `currentlyInsured` | booléen | | Accepte aussi `"oui"` / `"non"`, `"true"` / `"false"`, `1` / `0` |
| `currentInsurer` | chaîne | 120 | Nom de l'assureur actuel |
| `currentPremium` | nombre | | Cotisation mensuelle actuelle, en euros. `"89,50"` est accepté |
| `meta` | objet | | Objet libre conservé tel quel : campagne, identifiant interne, prix du lead |

> [!NOTE]
>
> **`email` ou `phone` : l'un des deux au moins est obligatoire.** Une livraison
> qui ne porte ni l'un ni l'autre est refusée avec un code `400`.

> [!NOTE]
>
> **Identité contre déclaration.** `birthDate`, `profession`, `address`,
> `postalCode` et `city` renseignent la fiche du contact : ce sont des faits sur
> la personne. Ils ne remplissent que ce qui est vide, et n'écrasent jamais ce
> que le cabinet a déjà saisi.
>
> `socialRegime`, `currentlyInsured`, `currentInsurer` et `currentPremium`
> restent attachés à la livraison, dans l'encadré « Lead reçu » de la fiche :
> c'est une déclaration faite un jour donné, pas un état du client. Une
> deuxième livraison ajoute sa propre déclaration sans effacer la précédente.

> [!WARNING]
>
> **N'envoyez jamais de champ `hp`.** C'est le piège à robots du formulaire web
> hébergé. Toute requête où il est rempli reçoit une réponse de succès et **est
> ignorée en silence** : aucun lead n'est créé, et rien ne vous le signale.

> **Valeurs acceptées pour source**
>
> Les valeurs ci-dessous désignent un canal d'acquisition et sont ramenées à
> l'une des trois catégories. **Toute autre valeur est conservée telle quelle**
> et devient la provenance du contact, visible et filtrable dans la colonne
> « Provenance » du tableau des contacts.
>
> | Envoyé | Enregistré |
> | - | - |
> | `ads`, `ad`, `meta`, `meta_ads`, `facebook`, `fb`, `google`, `google_ads`, `linkedin` | `ads` |
> | `call_center`, `callcenter`, `call`, `phone`, `telephone`, `centre_appel` | `call_center` |
> | `site`, `site_web`, `website`, `web`, `formulaire`, `form`, ou champ absent | `site` |
> | `oceads`, `hipto`, ou le nom de votre plateforme | le nom, tel quel |
>
> **Envoyez le nom de votre plateforme.** C'est ce qui permet au courtier de
> compter ce qu'il vous achète et de trier ses leads par fournisseur. Les
> accents, la casse et les séparateurs sont ignorés au rapprochement : `oceads`
> rejoint la provenance `Oceads` déjà proposée dans l'application, il ne crée
> pas une seconde entrée à côté.

> **Valeurs acceptées pour socialRegime**
>
> La valeur envoyée est ramenée à l'une des catégories ci-dessous. Une valeur
> hors liste n'est pas une erreur : elle est conservée telle quelle et
> affichée sur la fiche, ce qui vaut mieux qu'un champ vide.
>
> | Envoyé | Catégorie |
> | - | - |
> | `general`, `regime_general`, `salarie`, `cpam` | Régime général |
> | `tns`, `independant`, `travailleur_non_salarie`, `ssi`, `rsi` | Travailleur non salarié |
> | `agricole`, `msa`, `exploitant_agricole` | Agricole (MSA) |
> | `fonctionnaire`, `fonction_publique` | Fonction publique |
> | `retraite` | Retraité |
> | `etudiant` | Étudiant |
> | `alsace_moselle` | Alsace-Moselle |
> | `sans_emploi`, `demandeur_emploi`, `chomeur` | Sans emploi |
>
> Les accents, les espaces et les tirets sont ignorés : `Régime général` et
> `regime_general` sont la même valeur.

> **Valeurs acceptées pour mainNeed**
>
> `sante`, `prevoyance`, `retraite`, `epargne`, `assurance_vie`,
> `protection_juridique`, `mutuelle`, `prevoyance_entreprise`, `autre`.
>
> Une valeur hors liste n'est pas une erreur : le champ reste simplement vide
> sur la fiche. Il en va de même pour `civility`.

## La réponse

```json theme={null}
{
  "ok": true,
  "leadId": "8f3c1b42-...",
  "dealId": "1a907e55-...",
  "deduped": false
}
```

| Champ | Signification |
| - | - |
| `ok` | Vaut `true` quand la livraison a abouti |
| `leadId` | Identifiant du contact créé ou retrouvé |
| `dealId` | Identifiant de l'opportunité créée, ou `null` |
| `deduped` | Vaut `true` si un contact portant le même email existait déjà |

### Quand le contact existe déjà

Le rapprochement se fait sur l'email, sans limite d'ancienneté, à l'intérieur de
votre cabinet. Quand un contact correspond :

* **il n'est pas dupliqué**, il est complété. Un téléphone, un prénom ou un nom
  manquants sont renseignés, les valeurs déjà présentes ne sont jamais
  écrasées ;
* **la livraison est archivée** avec son message, son `meta` et son horodatage.
  Les livraisons précédentes restent consultables ;
* **le responsable des leads est alerté**, avec la mention que le contact était
  déjà connu ;
* **une opportunité est créée seulement si le `product` livré est nommé et
  diffère de celui de toutes les opportunités en cours** sur ce contact. Si vous
  ne renseignez pas `product`, ou si l'opportunité ouverte n'en porte pas, la
  demande est rattachée à celle qui existe déjà.

> [!TIP]
>
> Renseignez `product` si vous revendez le même prospect pour des produits
> différents : c'est ce qui permet à Assurevo de compter deux opportunités
> plutôt qu'une. Sans ce champ, une seule opportunité reste ouverte à la fois.

> [!TIP]
>
> Le champ `deduped` permet à votre fournisseur de réconcilier ses livraisons
> avec sa facturation : un prospect déjà connu reste un lead vendu, et il vous
> est bien signalé.

## Le retour d'information

Un fournisseur veut savoir ce que ses leads sont devenus : c'est ce qui lui
permet de calibrer ses campagnes, et à vous de discuter son prix. Assurevo peut
donc rappeler **son** URL à deux moments de la vie de l'opportunité.

**1. Renseigner l'URL du fournisseur**

Dans **Intégrations → Réception de leads**, le champ « Prévenir mon fournisseur ».
En `https` uniquement. Videz le champ pour arrêter les retours.

**2. Transmettre le secret de signature**

Il apparaît sous le champ dès que l'URL est enregistrée. Votre fournisseur
en a besoin pour vérifier que l'appel vient bien de vous.

**3. Envoyer un appel de test**

Le bouton « Envoyer un appel de test » déclenche une livraison
`event: "test"` immédiate et affiche le code renvoyé. À faire avant le
premier vrai lead.

### Les deux événements

| Événement | Déclenché quand |
| - | - |
| `devis_envoye` | L'opportunité issue du lead passe à l'étape « Proposition » |
| `contrat_signe` | Elle passe à l'étape « Signé » |

Seuls les contacts arrivés par la réception de leads déclenchent un retour. Un
aller-retour dans le pipeline ne renotifie pas : chaque couple (opportunité,
événement) part **une fois**.

### L'appel que vous recevez

```
POST https://votre-url-de-retour
Content-Type: application/json
X-Assurevo-Event: contrat_signe
X-Assurevo-Delivery: 0f0a2f7c-...
X-Assurevo-Signature: sha256=9c1f...
```

```json theme={null}
{
  "event": "contrat_signe",
  "occurredAt": "2026-08-27T14:41:00.000Z",
  "leadId": "8f3c1b42-...",
  "dealId": "1a907e55-...",
  "externalId": "LEAD-88213",
  "product": "Mutuelle senior",
  "stage": "signe",
  "receivedAt": "2026-08-20T09:12:00.000Z"
}
```

> [!NOTE]
>
> **Le retour ne réexpédie pas l'identité du contact.** Vous nous avez vendu ce
> lead : vous en détenez déjà le nom, l'email et le téléphone. Le retour ne vous
> apprend que ce que vous ne pouvez pas savoir, l'étape atteinte, et se
> rapproche de votre base par `externalId`.
>
> Une exception, et une seule : si votre livraison d'origine ne portait **aucun**
> identifiant, le retour ajoute `email`, `phone`, `firstName` et `lastName`,
> faute de quoi vous n'auriez rien à rapprocher. Envoyez un identifiant et vous
> ne recevrez que la référence.
>
> Le montant de la prime estimée ne sort pas d'Assurevo.

> [!TIP]
>
> **`externalId` est votre identifiant, pas le nôtre.** Il est repris du `meta`
> de la livraison d'origine, cherché sous `externalId`, `external_id`, `leadid`,
> `lead_id`, `reference` puis `id`. Envoyez le vôtre à l'ingestion et vous le
> retrouvez tel quel dans le retour : c'est ce qui permet de réconcilier sans
> stocker nos identifiants.

### Vérifier la signature

L'en-tête `X-Assurevo-Signature` porte le HMAC-SHA256 du **corps brut** de la
requête, calculé avec le secret affiché dans **Intégrations → Réception de leads**.

```js theme={null}
const attendu =
  "sha256=" +
  crypto.createHmac("sha256", SECRET).update(corpsBrut, "utf8").digest("hex");
// comparer avec l'en-tête reçu, en temps constant
```

### Réponse attendue et rejeu

Répondez en **`2xx`** : tout le reste compte comme un échec. Une livraison en
échec est rejouée avec un délai qui double à chaque tentative (2 min, 4 min,
8 min…, plafonné à 6 heures), jusqu'à 8 tentatives, puis abandonnée. La même
livraison peut donc vous parvenir deux fois si votre réponse s'est perdue :
traitez `X-Assurevo-Delivery` comme une clé d'idempotence.

## Les erreurs

| Code | Situation | Conduite à tenir |
| - | - | - |
| `400` | Ni `email` ni `phone` | Ne pas rejouer, la livraison est inexploitable |
| `400` | Email mal formé, champ trop long | Corriger la donnée avant tout nouvel envoi |
| `404` | Jeton inconnu, ou réception désactivée | Ne pas rejouer. Prévenir le courtier, lui seul peut réactiver ou régénérer |
| `500` | Incident côté Assurevo | Rejouer plus tard, en tenant compte de l'avertissement ci-dessous |

Les deux situations du `404` renvoient le même code, seul le message diffère.
Traitez-les de la même façon.

> [!WARNING]
>
> **Il n'existe pas encore de clé d'idempotence.**
>
> Une livraison comportant un **email**, rejouée plusieurs fois, ne crée pas de
> doublon : le rapprochement s'en charge et la réponse porte `deduped: true`.
> Une livraison comportant **uniquement un téléphone**, rejouée après un délai
> d'attente réseau, **crée un second contact**.
>
> Ne rejouez pas automatiquement une livraison dépourvue d'email. Signalez
> l'échec pour traitement manuel.

## Depuis Zapier (Typeform, Google Forms, Webflow…)

> [!WARNING]
>
> **Il n'y a pas de clé d'API Assurevo, et il n'y a rien à connecter.** Assurevo
> n'a pas d'application dans le catalogue Zapier : chercher « Assurevo » n'y
> donne aucun résultat, et un écran qui réclame une clé d'API ne pourra jamais
> l'accepter. L'authentification, c'est le jeton contenu dans l'URL webhook, et
> rien d'autre.

Le trajet est donc **Typeform → Webhooks by Zapier → Assurevo** :

**1. Déclencheur**

*Typeform → New Entry*, sur le formulaire concerné. Zapier propose ensuite
une variable par question.

**2. Action**

**Webhooks by Zapier → POST**. Pas « App Assurevo », qui n'existe pas, et
pas « Custom Request » qui demande d'écrire le corps à la main.

**3. URL**

Collez l'**URL de réception (webhook)** de *Intégrations → Réception de leads*, en entier, jeton
compris. Laissez *Payload Type* sur **JSON** et n'ajoutez aucun en-tête
d'authentification.

**4. Données**

Une ligne `email` (ou `phone`), et autant de lignes que vous voulez pour le
reste. Nommez `firstName`, `lastName`, `birthDate`, `message`… celles qui
correspondent au tableau plus haut pour qu'elles remplissent la fiche ;
laissez les autres au nom de votre question, elles seront conservées et
affichées telles quelles.

**5. Vérification**

*Test action* doit répondre `201`. Puis ouvrez le contact créé dans
Assurevo : l'encadré « Lead reçu » liste les réponses reçues.

> [!NOTE]
>
> **Ne confondez pas les deux liens de l'écran de réception de leads.** Le *lien du
> formulaire* (`app.assurevo.fr/f/…`) est une page à ouvrir dans un navigateur.
> L'*URL webhook* (`api.assurevo.fr/api/intake/…`) est celle à coller dans
> Zapier ou à donner à un fournisseur. Les deux contiennent le même jeton, et
> envoyer le premier à un partenaire lui fait reconstruire une adresse qui
> répond `404`.

## Limites actuelles

À connaître avant une mise en production, aucune ne bloque l'intégration :

* pas de clé d'idempotence, donc pas de rejeu sûr sans email ;
* jeton inconnu et réception désactivée partagent le code `404` ;
* l'URL de production écrit dans vos données réelles. Chaque environnement a
  ses propres tokens : un token de production ne fonctionne pas sur staging.
  Convenez d'une adresse email de test avec votre fournisseur, et attendez-vous
  à voir apparaître ses essais dans vos contacts ;
* aucune limitation de débit documentée. Si votre fournisseur livre par paquets
  de plusieurs centaines, signalez-le nous en amont.

## Ce qu'il faut vérifier auprès de votre fournisseur

Trois questions qui déterminent si cette intégration convient :

1. **Peut-il livrer en JSON vers une URL de votre choix ?** Certaines
   plateformes n'émettent qu'un format de formulaire figé, ou ne livrent que
   par email. Dans ce cas, cette API ne lui servira pas et il faut nous
   contacter pour envisager une autre voie.
2. **Livre-t-il au fil de l'eau, ou par lot à intervalle régulier ?**
3. **Quelle est sa politique de rejeu** en cas d'erreur réseau ou de code
   `5xx` ?
4. **Sait-il recevoir un retour** sur une URL à lui, et vérifier une signature
   HMAC ? C'est ce qui lui permet de savoir quels leads ont abouti.

> **[Séquences de relance](/automatisation/sequences.md)**
>
> Enchaîner automatiquement e-mails et tâches sur les leads qui arrivent.

> **[Nous contacter](mailto:contact@assurevo.fr)**
>
> Une plateforme qui ne sait pas livrer sur une URL ? Écrivez-nous.


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