Documentation

API et webhooks

Envoyez chaque prospect qualifié vers Zapier, Make, n8n ou votre CRM, lisez votre file depuis vos outils et enregistrez vos ventes automatiquement.

Inclus dès l'offre Pro. L'API et les webhooks se configurent dans Réglages. Adresse de l'API : https://lead-qualify.com/api/v1

Démarrer en 2 minutes

Dans Réglages → API, créez une clé (par exemple « Zapier »). Elle commence par qf_ et ne s'affiche qu'une fois : copiez-la.
Lancez cette commande dans un terminal, avec votre clé :

bash

curl "https://lead-qualify.com/api/v1/leads?route=appeler&limit=5" \
  -H "Authorization: Bearer qf_VOTRE_CLE"

Vous recevez vos cinq derniers prospects à appeler, au format JSON.

Authentification

Chaque requête porte la clé dans l'en-tête Authorization: Bearer qf_…. Une clé donne accès aux prospects de tout votre compte, tous formulaires confondus. Gardez-la côté serveur ou dans votre outil d'automatisation, jamais dans une page web publique. Une clé se révoque à tout moment depuis les réglages ; vous pouvez en créer une par outil.

Lister les prospects

GET/api/v1/leads

Prospects ayant terminé un formulaire, du plus récent au plus ancien.

Paramètre	Description
`route`	Action recommandée : appeler, a_qualifier, relancer, nourrir, ecarter.
`form`	Identifiant d'un formulaire : seulement ses prospects.
`since`	Date ISO 8601 : seulement les prospects terminés depuis (ex. 2026-09-01T00:00:00Z).
`limit`	Nombre de résultats, de 1 à 200. 50 par défaut.

bash

curl "https://lead-qualify.com/api/v1/leads?since=2026-09-01T00:00:00Z&limit=100" \
  -H "Authorization: Bearer qf_VOTRE_CLE"

Réponse 200

{
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "form": {
        "id": "11111111-1111-4111-8111-111111111111",
        "name": "Diagnostic découverte",
        "slug": "diagnostic"
      },
      "route": "appeler",
      "score": 82,
      "confidence": 0.84,
      "disqualified": false,
      "contact": {
        "first_name": "John",
        "last_name": "Doe",
        "email": "john.doe@exemple.fr",
        "phone": "+33 6 00 00 00 00"
      },
      "channel": "form",
      "utm": {
        "source": "linkedin"
      },
      "ab_variant": null,
      "key_answer": "Reprendre le sport durablement, dès que possible",
      "call_brief": "Partir de sa phrase : « je lâche dès que je voyage ». Point d'appui : urgence.",
      "diagnostic_url": "https://lead-qualify.com/d/22222222-2222-4222-8222-222222222222",
      "booked_at": null,
      "completed_at": "2026-09-30T09:14:02.000Z"
    }
  ]
}

Lire un prospect

GET/api/v1/leads/{id}

Le prospect complet : les mêmes champs que la liste, plus ses réponses brutes (answers, par identifiant de question) et l'issue enregistrée (outcome).

bash

curl "https://lead-qualify.com/api/v1/leads/00000000-0000-4000-8000-000000000000" \
  -H "Authorization: Bearer qf_VOTRE_CLE"

Réponse 200

{
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "form": {
      "id": "11111111-1111-4111-8111-111111111111",
      "name": "Diagnostic découverte",
      "slug": "diagnostic"
    },
    "route": "appeler",
    "score": 82,
    "confidence": 0.84,
    "disqualified": false,
    "contact": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@exemple.fr",
      "phone": "+33 6 00 00 00 00"
    },
    "channel": "form",
    "utm": {
      "source": "linkedin"
    },
    "ab_variant": null,
    "key_answer": "Reprendre le sport durablement, dès que possible",
    "call_brief": "Partir de sa phrase : « je lâche dès que je voyage ». Point d'appui : urgence.",
    "diagnostic_url": "https://lead-qualify.com/d/22222222-2222-4222-8222-222222222222",
    "booked_at": null,
    "completed_at": "2026-09-30T09:14:02.000Z",
    "answers": {
      "objectif": "reprendre",
      "demarrage": "maintenant",
      "budget": "1000_1500"
    },
    "outcome": {
      "result": "won",
      "amount_eur": 1440
    }
  }
}

Enregistrer une issue

POST/api/v1/leads/{id}/outcome

Indiquez ce qu'est devenu le prospect, par exemple depuis votre CRM quand une affaire est gagnée. Les ventes alimentent vos statistiques et affinent le tri de vos prochains prospects. Une nouvelle issue remplace la précédente.

Champ	Description
`result`	Obligatoire : won (a acheté), lost (n'a pas acheté), unreachable (injoignable), no_show (absent au rendez-vous).
`amount_eur`	Facultatif : montant de la vente en euros.

bash

curl -X POST "https://lead-qualify.com/api/v1/leads/00000000-0000-4000-8000-000000000000/outcome" \
  -H "Authorization: Bearer qf_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{"result": "won", "amount_eur": 1440}'

Réponse 200

{
  "ok": true
}

Format d'un prospect

Champ	Type	Description
`id`	texte	Identifiant unique du prospect.
`form`	objet	Formulaire d'origine : id, name, slug (adresse /f/slug).
`route`	texte	Action recommandée : appeler, a_qualifier, relancer, nourrir, ecarter.
`score`	nombre	Score sur 100, pour trier.
`confidence`	nombre	Confiance de l'évaluation, de 0 à 1.
`disqualified`	booléen	Écarté d'office (spam, hors cible explicite…).
`contact`	objet	Coordonnées saisies : first_name, last_name, email, phone.
`channel`	texte	Canal d'arrivée : form.
`utm`	objet	Paramètres UTM du lien : source, medium, campaign.
`ab_variant`	texte ou null	Test A/B : version reçue par le prospect, a ou b. null hors test.
`key_answer`	texte	Réponse clé, en une ligne.
`call_brief`	texte	Consigne pour ouvrir l'appel.
`diagnostic_url`	texte	Adresse du diagnostic reçu par le prospect.
`booked_at`	date ou null	Date de réservation d'un appel (Cal.com, Calendly).
`completed_at`	date	Date à laquelle il a terminé le formulaire.

Erreurs et limites

Toute erreur renvoie un JSON {"error": "…"} décrivant le problème. Chaque clé est limitée à 120 requêtes par minute ; au-delà, attendez la minute suivante (en-tête Retry-After).

Code	Signification
400	Requête invalide (par exemple : result inconnu).
401	Clé absente, invalide ou révoquée.
403	Offre sans API (Solo) ou abonnement inactif.
404	Prospect introuvable, ou appartenant à un autre compte.
413	Corps de requête trop volumineux.
429	Plus de 120 requêtes par minute.

Webhooks

Un webhook envoie chaque événement à votre adresse, en temps réel, sans que vous ayez à interroger l'API. Dans Réglages → Webhooks sortants, collez l'adresse fournie par votre outil (Zapier, Make, n8n, votre serveur) et choisissez les événements. Le bouton Tester envoie un exemple complet, marqué "test": true, pour que votre outil découvre tous les champs.

Élément	Valeur
Méthode	POST, corps JSON (Content-Type: application/json)
`X-Lead-Qualify-Event`	Nom de l'événement (ex. lead.qualified)
`X-Lead-Qualify-Signature`	Signature HMAC-SHA256 du corps, en hexadécimal, avec le secret du webhook
Délai	Répondez en moins de 10 secondes, avec un code 2xx
Nouvel essai	Aucun : un envoi en échec n'est pas renvoyé. Le dernier code reçu s'affiche dans les réglages.

Événements

Événement	Quand
`lead.qualified`	Un prospect a terminé un formulaire : il est évalué et son diagnostic est prêt.
`lead.booked`	Un prospect a réservé un appel (Cal.com, Calendly).
`lead.outcome`	Une issue a été enregistrée (depuis la fiche ou l'API).

Chaque envoi a la même enveloppe : l'événement, sa date, et ses données.

lead.qualified

{
  "event": "lead.qualified",
  "sent_at": "2026-09-30T09:14:03.120Z",
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "form": {
      "id": "11111111-1111-4111-8111-111111111111",
      "name": "Diagnostic découverte",
      "slug": "diagnostic"
    },
    "route": "appeler",
    "score": 82,
    "contact": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@exemple.fr",
      "phone": "+33 6 00 00 00 00"
    },
    "answers": {
      "Quel est votre objectif principal ?": "Reprendre le sport durablement",
      "Quand souhaitez-vous commencer ?": "Dès que possible",
      "Quel budget avez-vous prévu ?": "De 1 000 à 1 500 €"
    },
    "ab_variant": null,
    "key_answer": "Reprendre le sport durablement, dès que possible",
    "call_brief": "Partir de sa phrase : « je lâche dès que je voyage ». Point d'appui : urgence.",
    "url": "https://lead-qualify.com/app/leads/00000000-0000-4000-8000-000000000000"
  }
}

lead.booked

{
  "event": "lead.booked",
  "sent_at": "2026-09-30T10:02:41.000Z",
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "route": "appeler",
    "score": 82,
    "email": "john.doe@exemple.fr"
  }
}

lead.outcome

{
  "event": "lead.outcome",
  "sent_at": "2026-10-04T16:30:00.000Z",
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "result": "won",
    "amount_eur": 1440
  }
}

Dans lead.qualified, answers reprend chaque réponse sous l'intitulé de sa question, et url ouvre la fiche du prospect dans votre espace.

Vérifier la signature

Chaque webhook a son secret, visible dans les réglages. Recalculez le HMAC-SHA256 du corps brut reçu (avant toute transformation JSON) et comparez-le à l'en-tête X-Lead-Qualify-Signature. Zapier, Make et n8n n'en ont pas besoin ; c'est utile pour votre propre serveur.

Node.js

import { createHmac, timingSafeEqual } from "node:crypto";

function signatureValide(corpsBrut, signature, secret) {
  const attendue = createHmac("sha256", secret).update(corpsBrut).digest("hex");
  return signature?.length === attendue.length &&
    timingSafeEqual(Buffer.from(signature), Buffer.from(attendue));
}

PHP

$corps = file_get_contents('php://input');
$attendue = hash_hmac('sha256', $corps, $secret);
$valide = hash_equals($attendue, $_SERVER['HTTP_X_LEAD_QUALIFY_SIGNATURE'] ?? '');

Python

import hmac, hashlib

def signature_valide(corps_brut: bytes, signature: str, secret: str) -> bool:
    attendue = hmac.new(secret.encode(), corps_brut, hashlib.sha256).hexdigest()
    return hmac.compare_digest(attendue, signature or "")

Zapier, Make, n8n

Outil	Déclencheur à créer	Ensuite
Zapier	Webhooks by Zapier → Catch Hook. Copiez l'adresse fournie.	Collez-la dans Réglages → Webhooks, cliquez sur Tester, puis « Test trigger » dans Zapier : tous les champs apparaissent.
Make	Webhooks → Custom webhook. Copiez l'adresse.	Collez-la, cliquez sur Tester : Make détermine la structure des données. Enchaînez vers votre CRM, Google Sheets, Slack…
n8n	Nœud Webhook, méthode POST. Copiez l'adresse de production.	Collez-la et activez le workflow. Pour enregistrer une vente depuis n8n, utilisez un nœud HTTP Request vers /api/v1/leads/{id}/outcome.

Tester sans rien installer

Pour voir un webhook arriver sans outil d'automatisation, utilisez un service de réception en ligne, comme webhook.site ou Pipedream RequestBin : il vous donne une adresse unique et affiche chaque requête reçue, en-têtes et corps compris.

Ouvrez webhook.site : une adresse unique est créée pour vous.
Collez-la dans Réglages → Webhooks sortants, cochez les événements, ajoutez.
Cliquez sur Tester : la requête s'affiche aussitôt sur webhook.site.
Remplissez un de vos formulaires : l'événement lead.qualified réel arrive à son tour.

Ces services sont publics : n'y laissez pas passer de vraies données de prospects. Supprimez le webhook de test une fois l'essai terminé.