Leads

Capturer un lead depuis un funnel externe

Capture un nouveau lead dans Capturia depuis un funnel, formulaire ou outil tiers (Make, Zapier, n8n, landing custom). Une fois capturé, le lead apparaît immédiatement dans Mes Prospects côté dashboard et le bot SMS prend le relais dans les 30 secondes si le consentement et la configuration sont en ordre.

Contact déjà connu (courriel ou téléphone)

La fiche est résolue par courriel d'abord (insensible à la casse), puis par téléphone, en incluant les coordonnées secondaires déjà rattachées à une fiche. Capturer un lead dont le courriel ou le téléphone existe déjà réutilise et enrichit la fiche existante — le contact_id retourné est celui de cette fiche, jamais un doublon et jamais une erreur. Les coordonnées et champs cœur déjà remplis (nom, courriel, téléphone, pipeline, valeur, adresse...) ne sont pas écrasés ; les réponses de qualification (custom_fields) sont en revanche rafraîchies avec les dernières valeurs envoyées — une clé déjà présente est remplacée, une clé nouvelle s'ajoute. Un nouveau téléphone est conservé comme numéro secondaire quand la fiche en a déjà un. Si le courriel et le téléphone pointent deux fiches différentes, le courriel a priorité et aucune coordonnée n'est retirée à l'autre fiche.

La réponse expose contact_was_new pour distinguer les deux issues : sur une fiche existante (false), pipeline et assignment_status décrivent la demande résolue, pas forcément l'état persisté — la fiche conserve son pipeline, son étape et son vendeur déjà en place, et ignored_fields nomme ceux des champs du bloc pipeline qu'elle n'a pas pris (existing_contact_kept).

Champs reçus non pris (ignored_fields)

Une capture qui répond 200 dit ce qu'elle n'a pas pris. La réponse porte ignored_fields, une liste [{ field, reason }] toujours présente et vide quand tout a été appliqué :

• unknown_field — un nom que l'API ne connaît pas, à la racine, dans customData ou dans un bloc (pipeline.id, utm.utm_source) ;
• custom_field_not_defined — une clé de custom_fields sans définition du même nom dans le compte ;
• reserved_tag — une étiquette au nom réservé (tags[1]) ;
• system_not_active — un system_id qui n'est pas actif ;
• existing_contact_kept — un champ du bloc pipeline que la fiche existante a conservé ;
• sales_rep_not_found — un courriel de vendeur qui ne désigne aucun membre actif du compte ;
• submission_not_recorded — ce qui ne s'applique qu'avec une soumission enregistrée, quand elle ne l'est pas (existing_pipeline_contact, idempotent_replay) ;
• duplicate_field — une copie d'un champ reçu par plusieurs sources, écartée au profit d'une autre valeur.

Seule limite : sur une fiche existante, les champs d'identité et d'adresse déjà remplis, et l'attribution publicitaire déjà posée (règle du premier contact), sont conservés sans être nommés un à un (contact_was_new: false le signale).

Le lead est capturé dans tous ces cas : c'est un avertissement de montage, à lire au premier test d'une intégration. La liste est plafonnée à 50 entrées (ignored_fields_truncated), les champs mappés à la main avant ceux qu'un connecteur ajoute d'office.

Pipeline et étape

Le bloc pipeline désigne le pipeline et l'étape par leur identifiant texte (pipeline_slug, stage_slug), à copier dans le dashboard : Administration, Clés API, section « Identifiants de tes pipelines et étapes ». Un connecteur qui n'envoie que des paires clé/valeur (workflow GoHighLevel, Zapier) les envoie à plat : pipeline.pipeline_slug, pipeline.stage_slug. Sans pipeline_slug, l'étape est cherchée dans le pipeline par défaut.

Contact déjà en pipeline ouvert

Un lead dont le contact (résolu par courriel ou téléphone) est déjà dans une étape de pipeline ouverte (déjà pris en charge par un vendeur — non archivé, étape ni gagnée ni perdue) n'est pas re-soumis : la réponse renvoie status: existing_pipeline_contact, aucune nouvelle soumission n'est enregistrée et le bot SMS n'est pas redéclenché, pour ne pas écraser une conversation en cours. Les champs cœur nouvellement fournis enrichissent quand même le contact existant.

La dédup de retry reste prioritaire : un re-push reçu dans la fenêtre de 5 minutes est traité comme un retry (status: idempotent_replay, voir Idempotency) et conserve l'activity_id et l'original_created_at d'origine — existing_pipeline_contact ne s'applique qu'au-delà de cette fenêtre.

Idempotency

Le header Idempotency-Key est optionnel mais recommandé pour les retries côté client. Une 2e requête avec la même clé et le même payload renvoie la réponse d'origine sans dupliquer le lead. La clé est stockée 24h. Une 2e requête avec la même clé mais un payload différent retourne 409 idempotency_conflict. La RPC sous-jacente conserve par ailleurs sa propre fenêtre de dedup à 5 minutes. Cette fenêtre est par contact et indépendante du contenu : toute soumission d'un contact déjà capturé dans les 5 dernières minutes est traitée comme un retry (idempotent_replay) même si le payload diffère — la fiche est tout de même enrichie (dont les custom_fields, rafraîchis), mais aucune nouvelle activité, aucun tag, et pas de relance du bot SMS. Les mises à jour de la fiche restent réelles : une automatisation qui surveille un champ personnalisé réagit au changement de valeur, comme pour toute modification de la fiche. C'est aussi ce qui protège d'une double relance du bot quand un lead re-soumet son formulaire coup sur coup. Un Idempotency-Key différent ne contourne pas cette fenêtre : elle s'applique en base après tout cache miss. Deux soumissions volontairement distinctes du même contact ne produisent deux activités que si elles sont espacées de plus de 5 minutes.

Codes d'erreur custom

Pour des raisons historiques, certains rejets retournent des codes hors catalog standard :

• 422 — invalid_phone, missing_consent, invalid_email, invalid_payload, pipeline_not_found, stage_not_found (au lieu de validation_error / business_rule_violation). Body shape simplifiée propre à cette route — voir la réponse 422 ci-dessous.
• 429 — rate_limited_ip quand la limite IP (100 req/min) est atteinte (au lieu de rate_limit_exceeded). Le header X-RateLimit-Scope: ip identifie le scope de la limite déclenchée. Body shape simplifiée (pas de request_id ni details standard) — à harmoniser dans une phase ultérieure.

curl -X POST 'https://api.capturia.io/v1/leads/capture' \
  -H 'Authorization: Bearer cap_live_<your-key>' \
  -H 'Content-Type: application/json' \
  -d '{
  "phone": "+15145551234",
  "sms_consent": true,
  "first_name": "Alex",
  "last_name": "Tremblay",
  "email": "[email protected]",
  "source_label": "funnel-fb-jan",
  "utm": {
    "source": "facebook",
    "medium": "cpc",
    "campaign": "spring-2026"
  },
  "tags": [
    "lead-chaud",
    "vu-webinaire"
  ],
  "pipeline": {
    "pipeline_slug": "ventes-b2b",
    "stage_slug": "nouveau-lead",
    "deal_value": 2500,
    "expected_close_date": "2026-06-30",
    "assigned_sales_rep_email": "[email protected]"
  },
  "custom_fields": {
    "type_propriete": "maison_isolee",
    "delai_vente": "0_3_mois"
  },
  "address": "123 rue Principale, Montréal",
  "postal_code": "H2X 1Y4"
}'