Deduplication
Every POST /leads request runs automatic duplicate detection before inserting. This prevents polluting your database with duplicate entries from different sources.
Detection order
Section titled “Detection order”Klozeo checks the keys below in order and stops at the first one that finds an existing lead. Every check stays inside your account.
| Order | Key | Matches when | Result |
|---|---|---|---|
| 1 | email |
Same valid email, ignoring case and surrounding spaces | Merge into the existing lead |
| 2 | siren |
Same SIREN. A 14-digit SIRET is reduced to its 9-digit SIREN first | Merge into the existing lead |
| 3 | source_id |
Same source_id (surrounding spaces ignored) |
Merge into the existing lead |
| 4 | phone + name |
Same phone, character for character (only surrounding spaces are ignored, so +33 1 23 45 67 89 and 0123456789 do not match), and a name more than 80% similar |
Merge into the existing lead |
| 5 | name + city |
Same name and same city, ignoring case | Create a new lead and return potential_duplicate_id |
Name similarity ignores case and surrounding spaces and counts the single-character edits (insert, delete, replace) needed to turn one name into the other. The names match when those edits are fewer than 20% of the longer name’s length. Acme Corp and ACME Corp. match (1 edit in 10 characters); Acme Corp and ACME Corporation do not (7 edits in 16).
When several leads share a key
Section titled “When several leads share a key”- Email, SIREN,
source_id: within an account, at most one lead holds a given email (ignoring case), SIREN orsource_id, so a match is never ambiguous. Setting one of these to a value another lead already holds is refused with409 Conflict. - Phone + name: several leads can share a phone number. Klozeo looks at up to 5 leads with that phone, in no guaranteed order, and merges into the first whose name matches.
- Name + city: several leads can share a name and city.
potential_duplicate_idnames one of them, in no guaranteed order.
Valid emails
Section titled “Valid emails”Klozeo stores an email, and matches on it, only when it is valid. On every write (create, batch create, dashboard import, update, batch update, assistant save and merge), Klozeo first removes the surrounding spaces, keeps only the address of a form such as Jean Dupont <[email protected]>, and lowercases it: that lead stores [email protected].
An email is valid when it is one address of at most 254 characters, with exactly one @, something before the @, a domain that contains a dot and no empty part (acme..fr is not valid), and no space. Several addresses in one field ([email protected]; [email protected]) are not valid: Klozeo does not pick one. Exception: in the dashboard’s Google Maps import format, whose emails column is a list, Klozeo keeps the first address. The other addresses are kept in the other_emails attribute. Klozeo does not check that the domain exists.
An invalid email, such as n/a, contact or jean [email protected], never makes a request fail:
- The lead is written without it. A new lead has no email; a merge or an update keeps the email the lead already had.
- It never matches another lead: two companies sent with
"email": "n/a"stay two leads. - It counts as no email in scoring rules, exports and webhooks (
emailisnullinlead.created). - The response warns you with
"warnings": [{ "field": "email", "code": "invalid_email" }], without repeating the value. Each item of a batch create carries its ownwarnings. - The lead’s history keeps the value received, in the
invalid_emailfield of the entry’safter.
What a merge changes
Section titled “What a merge changes”When a duplicate is found at steps 1–4, the existing lead keeps its id and is updated:
- Each field you send with a value replaces the stored value. Fields you leave out, or send empty, are left unchanged.
- A merge never changes the
name, thestatus, theassigneeor the coordinates (latitude,longitude), even if you send them. Change them withPUT /leads/{id}. - Locked fields are never written.
tagsare added to the existing tags, never replaced: a tag such asdo-not-contactsurvives every import. Duplicates are ignored; existing tags keep their order. To replace the whole list, send an explicitPUT /leads/{id}.- Custom
attributesmerge by exact, case-sensitivename: a new name is added, an existing name with the same type is updated with the incoming value (includingfalse,0andnull). Attributes you do not send are left unchanged. An attribute is ignored and listed in the response with its reason when it is locked, when its type differs from the stored one, or when its name matches several stored attributes. - Do not contact is never lifted by a merge.
last_interaction_atis always bumped, even if no field changed: every new push counts as a new interaction.
Do not contact
Section titled “Do not contact”An opposition to contact (do_not_contact: true) is never lifted by a merge: an import that sends "do_not_contact": false, or no value at all, leaves it in place, with its original date and origin. An import that sends "do_not_contact": true adds the opposition to the existing lead. Only an explicit DELETE /leads/{id}/do-not-contact (dashboard or REST API, never MCP) lifts it, and the audit trail records who did it.
Field locks
Section titled “Field locks”Lock a field you have verified with POST /leads/{id}/locks/{field}, for example POST /leads/{id}/locks/email. From then on, no merge, import or company enrichment writes that field; the merge response lists it in skipped_locked_fields. You can still change it yourself with PUT /leads/{id}. Unlock it with DELETE /leads/{id}/locks/{field}. Each lock and unlock is recorded in the lead’s audit trail with the person who did it. → API reference
In the dashboard, open a lead: the Field locks panel lists the locked fields, and a lock icon marks them in the overview. Owners and editors pick fields under Choose locked fields; viewers see the locks without changing them.
When a person edits a field in the dashboard, Klozeo locks that field automatically, so the next merge or import keeps the correction. Writes from an API key, an assistant connection, an inbound source or an import never lock a field, except when the workspace lock policy freezes its first value.
Attribute locks
Section titled “Attribute locks”Lock a custom attribute the same way with POST /leads/{id}/attributes/{attr_id}/lock, and unlock it with DELETE /leads/{id}/attributes/{attr_id}/lock. From then on, no merge, import or inbound source writes that attribute, and company enrichment never fills it. The merge response lists it in attribute_changes as ignored, with the reason locked. You can still change it yourself with PUT /leads/{id}/attributes/{attr_id}, and it stays locked. Deleting the attribute removes its lock. Each lock and unlock is recorded in the lead’s audit trail with the person who did it. → API reference
When a person changes a custom attribute’s value or type in the dashboard, clearing it included, Klozeo locks that attribute automatically. Adding a new attribute does not lock it unless the workspace lock policy freezes its first value. Writes from an API key, an assistant connection, an inbound source or an import never lock an attribute, except when the workspace lock policy freezes its first value. The dashboard does not show attribute locks: a locked attribute carries "locked": true in GET /leads/{id} and GET /leads/{id}/attributes.
A workspace can also set a lock policy: a list of fields and custom attributes frozen after their first value. On each lead created after a name is added to the list, the first non-empty value received for it is locked automatically, whatever the channel. The policy never locks existing leads, and a lock removed on a lead is not set again. Removing a name from the list stops new locks; locks already set stay. → Lock policy
Response on duplicate
Section titled “Response on duplicate”{ "id": "cl_existing...", "message": "Duplicate detected, existing lead updated", "created_at": 1703520000, "duplicate": true, "attribute_changes": [ { "name": "segment", "action": "added" }, { "name": "budget", "action": "updated" }, { "name": "active", "action": "ignored", "reason": "type_mismatch" } ], "skipped_locked_fields": ["email"]}HTTP status is 200 OK (not 201) on a merge. id and created_at are those of the existing lead.
attribute_changes lists every incoming attribute in request order: added, updated (even when the value is unchanged), or ignored with a reason of locked, type_mismatch or ambiguous_name. It is omitted when the request sends no attributes. A merged item of POST /leads/batch and the MCP tools create_lead and batch_create_leads return the same list. If an attribute is invalid, the whole merge is refused and nothing is written.
skipped_locked_fields lists the incoming fields that were not written because they are locked. It is omitted when no locked field was sent. A merge can return both lists.
warnings is present when the request’s email was invalid: see Valid emails.
Potential duplicate
Section titled “Potential duplicate”On a name + city match only, a new lead is created (201 Created) and the response includes a hint:
{ "id": "cl_new...", "message": "Lead created successfully", "created_at": 1703520000, "potential_duplicate_id": "cl_similar..."}Both leads are kept. When you create a lead from the dashboard, a Possible duplicate detected notice shows the similar lead’s ID. Klozeo does not merge these for you: compare the two leads, then update or delete the one you do not want.
updated_at vs last_interaction_at
Section titled “updated_at vs last_interaction_at”| Field | Updates when |
|---|---|
updated_at |
A write sets at least one lead field, even to the value it already had |
last_interaction_at |
Any push arrives, including a merge that changes nothing |
Use sort_by=last_interaction_at&sort_order=DESC to find the leads with the most recent activity, independent of data changes.
Retries are not duplicates
Section titled “Retries are not duplicates”When a request times out, you do not know if it arrived. Send an Idempotency-Key header: if you send the same request with the same key again, Klozeo returns the first result and writes nothing a second time. The key guards the retries of one request. It does not compare leads: the detection keys above still decide, for every new request, whether it creates or merges. Two requests with different keys can still create two leads. → Retries and idempotency
Audit trail
Section titled “Audit trail”Every create, merge, update, delete and score change is recorded, and so is every custom attribute and note change, with the member who made it (for an API key, the account owner, and the key in api_key_id). In the dashboard, a lead’s Do not contact history names the API key for changes recorded with api_key_id, even after the key is revoked. In the dashboard, that history shows the acting member’s email to every member of the workspace, and a removed member appears as a former member. In the dashboard, a lead’s history tab shows its 50 most recent changes, without automatic score updates: see Note authors and the history tab. Fetch the history for a lead:
GET /leads/{id}/changes?limit=50{ "changes": [ { "id": "uuid-...", "lead_id": "cl_...", "workspace_id": "workspace_id", "user_id": "workspace_id", "actor_id": "actor_user_id", "api_key_id": "api_key_id", "action": "merged", "reason": "dedup:email", "created_at": 1703520000 } ], "count": 1}action |
When |
|---|---|
created |
New lead inserted |
merged |
Dedup merge into an existing lead (reason is dedup:email, dedup:siren, dedup:source_id or dedup:phone+name) |
updated |
Explicit PUT /leads/{id} (or batch update), a custom attribute added, changed or removed (reason is attribute:<name>), or a custom attribute locked or unlocked (reason is attribute_lock:locked:<name> or attribute_lock:unlocked:<name>) |
deleted |
Lead removed |
assigned, unassigned |
The assignee of a lead was set or removed; assignee holds the new assignee’s email on assigned, and before and after are empty |
note.created, note.updated, note.deleted |
A note added, edited or removed; before and after are the note. Deleting a lead writes one note.deleted entry per note, with reason lead:deleted |
scored |
The stored score changed; before and after hold only score. reason is score:refresh (after a lead or custom attribute write), score:recalculate (POST /leads/{id}/score or POST /leads/score/batch) or score:rules (automatic rescore after a scoring rule change, without actor_id) |
before / after are JSON snapshots of the lead (of the note for note.* entries). Default limit is 50 (max 100). A deleted lead’s history is kept for 30 days. A daily job then erases before, after and assignee, so the values are gone within 31 days of the deletion. Each entry keeps its action, date, the member or API key that acted, channel, reason and changed_fields, the names of the fields that changed. The history of a lead that is not deleted is not erased.
api_key_id is the id that GET /api-keys gives the API key behind a change made with a key, through the REST API or the MCP server. For such a change actor_id is the account owner. The api_key_id stays in the history after the key is revoked; entries written before this field was added have none. A change made in the dashboard has no api_key_id. A change made by an assistant connected through OAuth has none either, and its actor_id is the member who connected the assistant.