Développeurs et connecteurs

Branchez Kapzio à tous vos outils.

Une API simple pour faire entrer vos prospects, des webhooks signés pour en sortir, et des modèles prêts à importer dans Zapier, Make et n8n.

Authentification

Une clé par projet.

Créez une clé dans Kapzio : Mon organisation › Développeurs → « Créer une clé ». Elle ne donne accès qu'à son projet et se révoque à tout moment.

Toutes les requêtes passent en HTTPS sur https://app.kapzio.com/api/v1. Envoyez la clé dans l'en-tête Authorization: Bearer kz_live_… (ou X-Kapzio-Key si votre outil ne permet pas d'en-tête Authorization).

Les réponses sont en JSON. Les erreurs ont toujours la forme { "error": "…" } :

401 clé absente ou invalide
403 projet demandé hors de la clé
404 introuvable
422 paramètre invalide (le message dit lequel)

La clé est stockée sous forme d'empreinte : Kapzio ne peut pas vous la réafficher. Gardez-la dans le coffre de votre outil, jamais dans une page web publique.

Tester votre clé

curl https://app.kapzio.com/api/v1/projects \
  -H "Authorization: Bearer kz_live_…"

# 200 { "data": [ { "id": "c3d4…", "name": "Mon projet", … } ] }
# 401 { "error": "Clé API manquante (en-tête Authorization: Bearer …)" }

API v1

Points d'accès.

Les listes renvoient { data, has_more, next_cursor } : repassez cursor pour la page suivante, et updated_since pour ne relire que les nouveautés.

POST/api/v1/leads

Créer ou compléter un prospect

Dédoublonnage par e-mail puis par numéro d'entreprise : renvoyer le même prospect le complète. Champs reconnus : email, phone, company_name, company_number, contact_name, city, country, source, channel, utm ; tout autre champ est conservé dans data. Consentement SMS marketing (facultatif) : sms_consent (granted ou refused), avec sa preuve sms_consent_text (texte de la case acceptée), sms_consent_at (date du recueil) et sms_consent_source (outil ou page : « Typeform »…). Un accord transmis ne lève jamais un STOP.

curl -X POST https://app.kapzio.com/api/v1/leads \
  -H "Authorization: Bearer kz_live_…" \
  -H "Content-Type: application/json" \
  -d '{"email":"gerant@societe.be","company_name":"Société SRL","contact_name":"Marie Dupont","source":"zapier"}'

Réponse

{ "ok": true, "lead_id": "6f1c…" }   // 201

GET/api/v1/leads

Lister les prospects

Du plus récemment modifié au plus ancien. Filtres : stage (identifiant ou nom), temperature (chaud, tiede, froid), updated_since (ISO 8601), q (texte), limit (1 à 100, 50 par défaut), cursor. Chaque prospect indique son consentement SMS marketing : sms_consent (unknown, granted ou refused), sms_consent_at (date du dernier changement) et sms_consent_source (comment il a été obtenu : form, manual, import, api, sms_start, sms_stop). La preuve elle-même (texte accepté, empreinte IP) reste dans l'historique de la fiche et n'est jamais renvoyée.

curl "https://app.kapzio.com/api/v1/leads?temperature=chaud&updated_since=2026-10-01T00:00:00Z&limit=50" \
  -H "Authorization: Bearer kz_live_…"

Réponse

{ "data": [ { "id": "6f1c…", "company_name": "Société SRL", "stage": "Nouveau", "temperature": "chaud",
    "sms_consent": "granted", "sms_consent_at": "2026-11-03T09:42:17Z", "sms_consent_source": "form", … } ],
  "has_more": true, "next_cursor": "MjAyNi0xMC0z…" }

GET/api/v1/leads/:id

Fiche complète d'un prospect

Ajoute à la forme de liste (consentement SMS compris) : company_number, city, country, channel, tags, value_cents, lost_reason, utm, data, last_activity_at. 404 si le prospect n'appartient pas au projet de la clé.

curl https://app.kapzio.com/api/v1/leads/6f1c… \
  -H "Authorization: Bearer kz_live_…"

POST/api/v1/sync/leads

Synchroniser depuis un autre logiciel

external_id obligatoire : le prospect est retrouvé par cet identifiant (puis e-mail, puis numéro d'entreprise). stage accepte « won », « lost » ou un nom d'étape ; note ajoute une note à la fiche.

curl -X POST https://app.kapzio.com/api/v1/sync/leads \
  -H "Authorization: Bearer kz_live_…" \
  -H "Content-Type: application/json" \
  -d '{"external_id":"crm-4812","email":"gerant@societe.be","stage":"won"}'

Réponse

{ "ok": true, "lead_id": "6f1c…", "created": false }

POST/api/v1/events

Envoyer un événement (parcours, panier abandonné…)

Rattaché au prospect par e-mail. Idempotent avec l'en-tête Idempotency-Key : un même envoi rejoué n'est compté qu'une fois.

curl -X POST https://app.kapzio.com/api/v1/events \
  -H "Authorization: Bearer kz_live_…" \
  -H "Idempotency-Key: commande-1042" \
  -H "Content-Type: application/json" \
  -d '{"event":"onboarding.etape","data":{"email":"gerant@societe.be","step":2}}'

POST/api/v1/notes

Ajouter une note à un prospect

Prospect désigné par lead_id, ou par email (le plus récent du projet). content : 4 000 caractères au plus. 404 si le prospect n'est pas dans le projet de la clé.

curl -X POST https://app.kapzio.com/api/v1/notes \
  -H "Authorization: Bearer kz_live_…" \
  -H "Content-Type: application/json" \
  -d '{"email":"gerant@societe.be","content":"Rappelé, devis à envoyer vendredi"}'

Réponse

{ "ok": true, "id": "a41b…", "lead_id": "6f1c…", "created_at": "…" }   // 201

POST/api/v1/hooks

S'abonner à un événement (REST hooks)

Pour Zapier, Make ou tout outil qui s'abonne lui-même : target_url (https public) et event (ou events). L'abonnement vise le projet de la clé, apparaît dans la liste des webhooks et s'arrête si la clé est révoquée. Le secret de signature n'est renvoyé qu'à la création ; la même target_url déjà abonnée renvoie 200 avec ses événements remplacés. GET /hooks liste les abonnements de la clé.

curl -X POST https://app.kapzio.com/api/v1/hooks \
  -H "Authorization: Bearer kz_live_…" \
  -H "Content-Type: application/json" \
  -d '{"target_url":"https://hooks.zapier.com/hooks/standard/123/abc","event":"lead.created"}'

Réponse

{ "id": "9b2e…", "target_url": "https://hooks.zapier.com/…", "events": ["lead.created"], "event": "lead.created",
  "project_id": "c3d4…", "active": true, "created": true, "secret": "whsec_…" }   // 201

DELETE/api/v1/hooks/:id

Se désabonner

Supprime un abonnement créé par l'API pour le projet de la clé (aussi DELETE /hooks?target_url=…). Les webhooks ajoutés dans l'application ne sont jamais supprimés par l'API. 404 si l'abonnement n'existe plus.

curl -X DELETE https://app.kapzio.com/api/v1/hooks/9b2e… -H "Authorization: Bearer kz_live_…"

Réponse

{ "ok": true, "deleted": 1 }

GET/api/v1/hooks/sample?event=…

Exemples d'un événement

Jusqu'à trois envois récents du projet, sous la forme exacte d'un webhook (avec sample: true), ou un exemple complet si le projet n'a encore rien de ce type. Sert aux « exemples » de Zapier et à la structure de données de Make.

curl "https://app.kapzio.com/api/v1/hooks/sample?event=invoice.paid" -H "Authorization: Bearer kz_live_…"

GET/api/v1/projects

Projet de la clé

Une clé API correspond à un projet : la réponse contient ce seul projet (id, name, slug, color, website, countries, archived, created_at).

curl https://app.kapzio.com/api/v1/projects -H "Authorization: Bearer kz_live_…"

GET/api/v1/stages

Étapes du pipeline

Dans l'ordre, avec leur nature : open, won ou lost.

curl https://app.kapzio.com/api/v1/stages -H "Authorization: Bearer kz_live_…"

Webhooks sortants

Kapzio vous prévient.

Ajoutez une adresse de réception dans Mon organisation › Développeurs (ou Intégrations), ou abonnez-vous par l'API (POST /hooks). Kapzio y envoie un POST JSON à chaque événement choisi, en quelques minutes.

Événements

lead.createdNouveau prospect, quelle que soit sa source (formulaire, API, publicité, e-mail, WhatsApp, rendez-vous).
lead.stage_changedLe prospect change d'étape ; data.previous_stage indique l'étape quittée.
lead.wonLe prospect passe dans une étape gagnée.
meeting.createdRendez-vous planifié (par l'équipe ou réservé en ligne par le prospect).
quote.acceptedDevis accepté et signé en ligne par le prospect.
invoice.paidFacture client passée au statut payée (virement rapproché, paiement en ligne ou saisie manuelle).
pingEnvoyé par le bouton « Tester » : vérifie que l'adresse répond. « Envoyer un exemple » envoie au contraire un vrai événement du projet, marqué test: true.

Livraison

Réussite : réponse 2xx en moins de 10 secondes.
Sinon, nouvel essai après 1 min, 5 min, 30 min, 2 h et 12 h, puis abandon (visible dans le journal du webhook).
X-Kapzio-Delivery (aussi dans id) est unique par envoi : servez-vous-en pour ignorer un doublon.

Exemple : lead.created

POST https://hooks.zapier.com/hooks/catch/…
Content-Type: application/json
User-Agent: Kapzio-Webhooks/1.0
X-Kapzio-Event: lead.created
X-Kapzio-Delivery: 3d9b6a52-6c1e-4b8e-9a51-2f0c1b7e4d10
X-Kapzio-Signature: sha256=8f2c…e41a

{
  "id": "3d9b6a52-6c1e-4b8e-9a51-2f0c1b7e4d10",
  "event": "lead.created",
  "occurred_at": "2026-10-31T09:42:17.512Z",
  "org_id": "a1b2…",
  "project_id": "c3d4…",
  "data": {
    "lead": {
      "id": "6f1c…", "project_id": "c3d4…",
      "company_name": "Société SRL", "contact_name": "Marie Dupont",
      "email": "gerant@societe.be", "phone": "+32470123456",
      "source": "Formulaire du site", "stage": "Nouveau", "stage_id": "e5f6…", "stage_kind": "open",
      "temperature": "tiede", "score": 42,
      "created_at": "2026-10-31T09:42:17.401Z", "updated_at": "2026-10-31T09:42:17.401Z",
      "sms_consent": "granted", "sms_consent_at": "2026-10-31T09:42:17.598Z", "sms_consent_source": "form"
    }
  }
}

Autres charges utiles

lead.stage_changed

"data": { "lead": { … }, "previous_stage": "Contacté", "previous_stage_id": "…", "previous_stage_kind": "open" }

meeting.created

"data": { "meeting": { "id", "title", "kind", "starts_at", "duration_min", "location", "link", "status", "created_at" }, "lead": { … } | null }

quote.accepted

"data": { "quote": { "id", "number", "title", "total_ht", "total_vat", "total_ttc", "accepted_name", "decided_at" }, "lead": { … } | null }

invoice.paid

"data": { "invoice": { "id", "number", "kind", "issue_date", "due_date", "currency", "ht_cents", "vat_cents", "ttc_cents", "due_cents", "paid_cents", "paid_at", "structured_ref", "buyer_name", "buyer_email", … }, "lead": { … } | null }

Vérifier la signature

Chaque requête porte X-Kapzio-Signature: sha256=<hex>, le HMAC-SHA256 du corps brut calculé avec le secret du webhook (affiché une seule fois à la création, renouvelable). Recalculez-le et comparez en temps constant : un appel dont la signature ne correspond pas ne vient pas de Kapzio.

Node.js

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

// rawBody : le corps exact reçu (texte), AVANT tout JSON.parse
export function signatureValide(rawBody, header, secret) {
  const attendu = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(attendu);
  const b = Buffer.from(header || "");
  return a.length === b.length && timingSafeEqual(a, b);
}

Python

import hmac, hashlib

def signature_valide(raw_body: bytes, header: str, secret: str) -> bool:
    attendu = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(attendu, header or "")

Pas à pas

Zapier, Make et n8n.

Dans chaque outil, deux sens : recevoir les événements Kapzio (webhook sortant), ou créer des prospects dans Kapzio (API).

Zapier

Kapzio → Zapier

Créez un Zap, déclencheur « Webhooks by Zapier » → « Catch Hook ». Copiez l'adresse proposée (https://hooks.zapier.com/hooks/catch/…).
Dans Kapzio : Mon organisation › Développeurs (ou Intégrations) → « Ajouter un webhook ». Collez l'adresse, choisissez l'événement (ex. « Nouveau prospect ») et le projet.
Copiez le secret affiché une seule fois et gardez-le (pour vérifier la signature dans une étape « Code by Zapier », facultatif).
Choisissez l'événement dans « Envoyer un exemple » côté Kapzio, puis « Test trigger » dans Zapier : le dernier vrai événement du projet apparaît, avec tous les champs data.lead.*.
Ajoutez l'action voulue (Google Sheets, Slack, Gmail, votre CRM…) en associant les champs, puis publiez le Zap.

Zapier → Kapzio

Déclencheur : votre outil (Typeform, Google Forms, Calendly, Facebook Lead Ads…).
Action « Webhooks by Zapier » → « POST ». URL : https://app.kapzio.com/api/v1/leads ; type de données : json.
Données : email, company_name, contact_name, phone, source (ex. « Typeform »), associés aux réponses du formulaire.
En-têtes : Authorization = Bearer kz_live_… (clé API du projet, Mon organisation › Développeurs).
Testez : la réponse { "ok": true, "lead_id": … } confirme la création. Le prospect apparaît dans le pipeline du projet.

Make

Kapzio → Make

Nouveau scénario, module « Webhooks » → « Custom webhook » → « Add ». Copiez l'adresse (https://hook.eu1.make.com/…).
Dans Kapzio, ajoutez un webhook sortant avec cette adresse et les événements voulus.
Dans Make, cliquez « Redetermine data structure », puis « Envoyer un exemple » dans Kapzio : Make apprend la forme réelle des données.
Enchaînez vos modules (Google Sheets → Add a row, Slack → Create a message…) en associant 1.data.lead.*. Activez le scénario.
Pour filtrer, ajoutez un filtre sur 1.event (ex. égal à lead.created).

Make → Kapzio

Module déclencheur de votre outil, ou « Webhooks → Custom webhook » si l'outil envoie lui-même un webhook (Typeform).
Module « HTTP » → « Make a request ». URL : https://app.kapzio.com/api/v1/leads ; méthode POST.
En-tête Authorization : Bearer kz_live_… ; corps « Raw », type JSON, avec email, company_name, contact_name, phone, source.
Cochez « Parse response » pour récupérer lead_id et l'utiliser dans les modules suivants.

n8n

Kapzio → n8n

Nœud « Webhook » : méthode POST, chemin au choix, option « Raw Body » activée si vous vérifiez la signature. Copiez l'URL de production.
Dans Kapzio, ajoutez un webhook sortant avec cette URL, puis activez le workflow dans n8n.
Nœud « IF » sur l'en-tête x-kapzio-event pour aiguiller les événements, puis vos nœuds (Google Sheets, Slack, base de données…).
Signature (facultatif) : nœud « Crypto » → HMAC, SHA256, encodage hex, sur le corps brut, avec le secret du webhook ; comparez à l'en-tête x-kapzio-signature (sans « sha256= »).

n8n → Kapzio

Déclencheur de votre outil (nœud Typeform Trigger, Google Sheets Trigger…) ou nœud « Webhook ».
Nœud « HTTP Request » : POST https://app.kapzio.com/api/v1/leads, authentification « Header Auth » (Authorization = Bearer kz_live_…).
Corps JSON : email, company_name, contact_name, phone, source. Le nœud renvoie lead_id.

Modèles

Prêts à importer.

Make : Créer un scénario → ⋯ → Importer le blueprint. n8n : menu ⋯ → Import from File. Reliez ensuite vos comptes Google, Slack et votre clé API.

Nouveau prospect Kapzio → Google Sheets + Slack

Chaque nouveau prospect ajoute une ligne à votre tableur et prévient votre canal Slack.

Make (blueprint)n8n (workflow)

Formulaire Typeform / Google Forms → Kapzio

Chaque réponse crée ou complète un prospect dans le bon projet, avec la source « Typeform ».

Make (blueprint)n8n (workflow)

Modèles Zapier

Zapier n'importe pas de fichier : recréez ces deux Zaps en deux minutes avec le guide ci-dessus.

Nouveau prospect → Google Sheets + Slack : Catch Hook (Kapzio, lead.created) → Google Sheets « Create Spreadsheet Row » → Slack « Send Channel Message ».
Typeform → Kapzio : Typeform « New Entry » → Webhooks by Zapier « POST » vers /api/v1/leads avec la clé API.

Une application Kapzio officielle pour le répertoire Zapier (déclencheurs nouveau prospect, changement d'étape, devis signé et facture payée ; actions créer un prospect et ajouter une note) est préparée et attend sa validation par Zapier. Elle s'appuie sur les abonnements REST hooks décrits plus haut.

Besoin d'un branchement particulier ? Écrivez-nous : nous vous aidons à le mettre en place.

Commencer

Essayez Kapzio sur vos marques.

14 jours gratuits, sans carte bancaire. Vos premiers prospects arrivent dès le premier formulaire collé.

Essayer 14 jours gratuitement Demander une démo