Use Klozeo in your n8n workflows
If you’re running n8n workflows that push leads into Airtable, you’ve hit this wall: Airtable works fine as a read source, but writing back (updating a field after an enrichment step, marking a lead as qualified after a scoring run) is fragile. You’re fighting rate limits, an upsert limited to one to three merge fields, and existing duplicates that make it fail instead of merging.
Klozeo’s REST API is built specifically for this. Same HTTP Request nodes in n8n, no SQL required, deduplication on every POST /leads.
Authentication
Section titled “Authentication”Add an X-API-Key header to every request. Get your key from the dashboard under API Keys.
In n8n, store it as a Credential (HTTP Header Auth):
| Field | Value |
|---|---|
| Name | X-API-Key |
| Value | sk_live_... |
Create or update a lead
Section titled “Create or update a lead”POST /leads runs deduplication before every insert. If a lead with the same email, SIREN or source_id already exists (or the same phone with a similar name), it merges instead of creating a duplicate, and returns the existing lead’s ID.
n8n HTTP Request node:
| Setting | Value |
|---|---|
| Method | POST |
| URL | https://api.klozeo.com/api/v1/leads |
| Auth | HTTP Header Auth (your credential) |
| Body | JSON |
{ "name": "{{ $json.company_name }}", "source": "n8n-webhook", "email": "{{ $json.email }}", "city": "{{ $json.city }}", "source_id": "{{ $json.external_id }}"}Use source_id to pass your external system’s ID: Klozeo matches on it when the email and SIREN find nothing. You can call it on every run: a lead sent again merges only when it matches on the email, the SIREN, the source_id or the phone with a similar name. Without any of those keys, each run creates a lead.
Response when created (201):
{ "id": "cl_...", "message": "Lead created successfully", "created_at": 1703520000 }Response when merged (200):
{ "id": "cl_existing...", "message": "Duplicate detected, existing lead updated", "created_at": 1703520000, "duplicate": true }Either way, id is valid and you can use it in downstream nodes. The response does not contain the lead’s fields; fetch them with GET /leads/{{ $json.id }} if you need them. A merge never changes the lead’s name, status or GPS coordinates (latitude, longitude).
Update a lead
Section titled “Update a lead”Once you have a cl_ ID (from a previous create step, a webhook, or a lookup), you can patch any field:
PUT https://api.klozeo.com/api/v1/leads/{{ $json.id }}{ "status": "qualified", "rating": 4.5}Only include fields you want to change. status is stored as sent (up to 50 characters). Send a value from your workspace’s status list: the dashboard flags any other value as “Not in the list”.
This is the write-back that Airtable makes painful. One node, no workarounds.
Filter leads
Section titled “Filter leads”GET https://api.klozeo.com/api/v1/leads?filter=and.eq.status.new&filter=and.gte.score.60&limit=100Filter format: logic.operator.field.value. Chain multiple filter params with &.
Common operators: eq, neq, gt, gte, lt, lte, contains, is_empty, is_not_empty.
In n8n, set the URL with Query Parameters in the node:
| Parameter | Value |
|---|---|
filter |
and.eq.status.new |
filter |
and.gte.score.60 |
limit |
100 |
n8n sends both filter params; Klozeo combines them with AND logic.
Paginate with cursor from the response’s next_cursor field. Use a Loop node + an IF node on has_more to walk all pages.
Batch create
Section titled “Batch create”If you’re importing a list (form submissions, scraped data, a CSV), use batch create:
POST https://api.klozeo.com/api/v1/leads/batch{ "leads": [ ]}Up to 100 leads per request (Free) or 500 (Pro and Scale). The response is 201 Created when every item succeeds and 207 Multi-Status when at least one fails: check its errors array. Merged items appear in created with "duplicate": true.
Migrate from Airtable
Section titled “Migrate from Airtable”Option 1: CSV import (quickest)
- Export your Airtable base as CSV.
- Rename the CSV header row to Klozeo field names (
name,source,email,phone,city, …).nameandsourceare required; other columns are ignored. See Import from a file for the full list. - In Klozeo: Leads → Import → CSV → upload the file.
- Deduplication runs on every row on the same keys: a row that carries an email, a SIREN, a
source_idor a phone with a similar name updates the existing lead, the others create a lead.
Option 2: n8n workflow
Useful if you want to migrate incrementally or keep both in sync during a transition.
- Airtable node → list all records.
- Split In Batches (100 at a time).
- HTTP Request →
POST /leads/batchto Klozeo. - Optional: store the Airtable record ID in
source_idso Klozeo can match them on future runs.
What you gain
Section titled “What you gain”Switching Klozeo in as your write target:
- Dedup on every
POST /leads: no moreUPSERTgymnastics or checking-then-inserting in two nodes. - Write-back without friction: update status, rating, or any field from any point in your workflow.
- Scoring rules: define expressions once, scores update automatically on every lead change. No formula columns to maintain.
- Webhooks: subscribe to
lead.created,lead.updatedetc. to trigger downstream workflows instead of polling.
→ API Reference: Leads · Filtering guide · Scoring Rules
Use the created lead in a webhook workflow
Section titled “Use the created lead in a webhook workflow”Subscribe a Webhook node to lead.created. The event contains the creation request
fields, the generated lead ID in payload.id, and created_at, updated_at and
last_interaction_at.
With n8n’s default Webhook node output, use {{ $json.body.payload.id }} in the
next HTTP Request node, for example PUT /leads/<id>. No search request is needed. Dedup merges emit lead.updated.
In Make, use Webhooks → Custom webhook, then map payload → id from the
received JSON into the next HTTP module’s /leads/<id> URL. The same ID is returned
by the original POST /leads response.