Skip to content

Deduplication

Every POST /leads request runs automatic duplicate detection before inserting. This prevents polluting your database with duplicate entries from different sources.

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).

  • Email, SIREN, source_id: within an account, at most one lead holds a given email (ignoring case), SIREN or source_id, so a match is never ambiguous. Setting one of these to a value another lead already holds is refused with 409 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_id names one of them, in no guaranteed order.

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 (email is null in lead.created).
  • The response warns you with "warnings": [{ "field": "email", "code": "invalid_email" }], without repeating the value. Each item of a batch create carries its own warnings.
  • The lead’s history keeps the value received, in the invalid_email field of the entry’s after.

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, the status, the assignee or the coordinates (latitude, longitude), even if you send them. Change them with PUT /leads/{id}.
  • Locked fields are never written.
  • tags are added to the existing tags, never replaced: a tag such as do-not-contact survives every import. Duplicates are ignored; existing tags keep their order. To replace the whole list, send an explicit PUT /leads/{id}.
  • Custom attributes merge by exact, case-sensitive name: a new name is added, an existing name with the same type is updated with the incoming value (including false, 0 and null). 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_at is always bumped, even if no field changed: every new push counts as a new interaction.

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.

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.

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

{
"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.

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.

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.

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

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",
"before": { "name": "Acme", "email": "[email protected]" },
"after": { "name": "Acme", "email": "[email protected]" },
"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.