Utiliser Klozeo dans vos workflows n8n

Si vos workflows n8n envoient des leads dans Airtable, vous connaissez ce mur : Airtable fait très bien l’affaire comme source de lecture, mais l’écriture en retour (mettre à jour un champ après une étape d’enrichissement, marquer un lead comme qualifié après un scoring) reste fragile. Vous vous battez contre les limites de débit, un upsert qui accepte trois champs de fusion au plus, et des doublons existants qui le font échouer au lieu de fusionner.

L’API REST de Klozeo est conçue pour ça. Les mêmes nœuds HTTP Request dans n8n, aucun SQL à écrire, un dédoublonnage à chaque POST /leads.

Authentification

Ajoutez un en-tête X-API-Key à chaque requête. Votre clé se trouve dans le tableau de bord, dans Clés API.

Dans n8n, enregistrez-la comme Credential (HTTP Header Auth) :

Champ	Valeur
Name	`X-API-Key`
Value	`sk_live_...`

Créer ou mettre à jour un lead

POST /leads lance le dédoublonnage avant chaque insertion. Si un lead avec le même email, le même SIREN ou le même source_id existe déjà (ou le même téléphone avec un nom similaire), il est fusionné au lieu de créer un doublon, et la réponse renvoie l’ID du lead existant.

Nœud HTTP Request de n8n :

Réglage	Valeur
Method	POST
URL	`https://api.klozeo.com/api/v1/leads`
Auth	HTTP Header Auth (votre identifiant)
Body	JSON

{
  "name": "{{ $json.company_name }}",
  "source": "n8n-webhook",
  "email": "{{ $json.email }}",
  "city": "{{ $json.city }}",
  "source_id": "{{ $json.external_id }}"
}

Utilisez source_id pour transmettre l’ID de votre système externe : Klozeo s’appuie dessus quand l’email et le SIREN ne trouvent rien. Vous pouvez répéter l’appel à chaque exécution : un lead renvoyé ne fusionne que s’il correspond sur l’email, le SIREN, le source_id ou le téléphone avec un nom similaire. Sans aucune de ces clés, chaque exécution crée un lead.

Réponse à la création (201) :

{ "id": "cl_...", "message": "Lead created successfully", "created_at": 1703520000 }

Réponse en cas de fusion (200) :

{ "id": "cl_existing...", "message": "Duplicate detected, existing lead updated", "created_at": 1703520000, "duplicate": true }

Dans les deux cas, id est valide et utilisable dans les nœuds suivants. La réponse ne contient pas les champs du lead ; récupérez-les avec GET /leads/{{ $json.id }} si vous en avez besoin. Une fusion ne modifie jamais le name, le status ni les coordonnées GPS (latitude, longitude) du lead.

Mettre à jour un lead

Une fois que vous avez un ID cl_, obtenu à l’étape de création précédente, par un webhook ou par une recherche, vous pouvez modifier n’importe quel champ :

PUT https://api.klozeo.com/api/v1/leads/{{ $json.id }}

{
  "status": "qualified",
  "rating": 4.5
}

N’indiquez que les champs à modifier. status est stocké tel qu’envoyé (50 caractères maximum). Envoyez une valeur de la liste des statuts de votre espace : le tableau de bord marque toute autre valeur « Hors de la liste ».

C’est l’écriture en retour qu’Airtable rend pénible. Un seul nœud, aucun contournement.

Filtrer les leads

GET https://api.klozeo.com/api/v1/leads?filter=and.eq.status.new&filter=and.gte.score.60&limit=100

Format du filtre : logic.operator.field.value. Enchaînez plusieurs paramètres filter avec &.

Opérateurs courants : eq, neq, gt, gte, lt, lte, contains, is_empty, is_not_empty.

Dans n8n, renseignez l’URL avec Query Parameters dans le nœud :

Paramètre	Valeur
`filter`	`and.eq.status.new`
`filter`	`and.gte.score.60`
`limit`	`100`

n8n envoie bien les deux paramètres filter : Klozeo les combine avec une logique AND.

Paginez avec cursor, à partir du champ next_cursor de la réponse. Utilisez un nœud Loop et un nœud IF sur has_more pour parcourir toutes les pages.

Création en lot

Si vous importez une liste (réponses de formulaire, données scrapées, un CSV), utilisez la création en lot :

POST https://api.klozeo.com/api/v1/leads/batch

{
  "leads": [
    { "name": "Acme", "source": "import", "email": "[email protected]" },
    { "name": "Globex", "source": "import", "email": "[email protected]" }
  ]
}

Jusqu’à 100 leads par requête (Free) ou 500 (Pro et Scale). La réponse est 201 Created quand tous les éléments réussissent et 207 Multi-Status quand au moins un échoue : consultez son tableau errors. Les éléments fusionnés apparaissent dans created avec "duplicate": true.

Migrer depuis Airtable

Option 1 : import CSV (le plus rapide)

Exportez votre base Airtable en CSV.
Renommez la ligne d’en-tête du CSV avec les noms de champs Klozeo (name, source, email, phone, city, …). name et source sont obligatoires ; les autres colonnes sont ignorées. Voir Importer depuis un fichier pour la liste complète.
Dans Klozeo : Leads → Importer → CSV → importez le fichier.
Le dédoublonnage s’applique à chaque ligne sur les mêmes clés : une ligne qui porte un email, un SIREN, un source_id ou un téléphone avec un nom similaire met à jour le lead existant, les autres créent un lead.

Option 2 : workflow n8n

Utile si vous voulez migrer progressivement ou garder les deux systèmes synchronisés pendant la transition.

Airtable node → lister tous les enregistrements.
Split In Batches (100 à la fois).
HTTP Request → POST /leads/batch vers Klozeo.
Facultatif : stockez l’ID d’enregistrement Airtable dans source_id pour que Klozeo les reconnaisse aux exécutions suivantes.

Ce que vous y gagnez

En faisant de Klozeo votre cible d’écriture :

Dédoublonnage à chaque POST /leads : plus de contorsions UPSERT ni de vérification puis insertion en deux nœuds.
Écriture en retour sans friction : mettez à jour le statut, la note ou n’importe quel champ depuis n’importe quel point de votre workflow.
Règles de scoring : définissez vos expressions une fois, les scores se mettent à jour automatiquement à chaque changement de lead. Aucune colonne de formule à maintenir.
Webhooks : abonnez-vous à lead.created, lead.updated, etc. pour déclencher vos workflows en aval au lieu d’interroger l’API en boucle.

→ Référence API : Leads · Guide des filtres · Règles de scoring

Utiliser le lead créé dans un workflow webhook

Abonnez un nœud Webhook à lead.created. L’événement contient les champs de la requête de création et l’ID du lead généré dans payload.id. Avec la sortie par défaut du nœud Webhook de n8n, utilisez {{ $json.body.payload.id }} dans le nœud HTTP Request suivant, par exemple PUT /leads/<id>. Aucune requête de recherche n’est nécessaire. Les fusions issues du dédoublonnage émettent lead.updated.

Dans Make, utilisez Webhooks → Custom webhook, puis mappez payload → id depuis le JSON reçu vers l’URL /leads/<id> du module HTTP suivant. Le même ID est renvoyé par la réponse du POST /leads d’origine.