Réception de leads (API)

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

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

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

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.

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.

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
    }
  }'

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

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.

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.

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

{
  "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à.

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.

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

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.

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.

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

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

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.

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.

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.

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…)

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 :

Déclencheur

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

Action

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

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.

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.

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.

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 :

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.
Livre-t-il au fil de l’eau, ou par lot à intervalle régulier ?
Quelle est sa politique de rejeu en cas d’erreur réseau ou de code 5xx ?
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

Enchaîner automatiquement e-mails et tâches sur les leads qui arrivent.

Nous contacter

Une plateforme qui ne sait pas livrer sur une URL ? Écrivez-nous.

​Avant de commencer

​L’appel

​Les champs

​La réponse

​Quand le contact existe déjà

​Le retour d’information

​Les deux événements

​L’appel que vous recevez

​Vérifier la signature

​Réponse attendue et rejeu

​Les erreurs

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

​Limites actuelles

​Ce qu’il faut vérifier auprès de votre fournisseur

Séquences de relance

Nous contacter

Avant de commencer

L’appel

Les champs

La réponse

Quand le contact existe déjà

Le retour d’information

Les deux événements

L’appel que vous recevez

Vérifier la signature

Réponse attendue et rejeu

Les erreurs

Depuis Zapier (Typeform, Google Forms, Webflow…)

Limites actuelles

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