Skip to main content
POST
/
v1
/
contacts
/
merge
Merge Contacts
curl --request POST \
  --url https://api.example.com/v1/contacts/merge \
  --header 'Content-Type: application/json' \
  --data '
{
  "primary_id": "<string>",
  "duplicate_ids": [
    {}
  ],
  "overwrite": true,
  "dry_run": true
}
'
{
  "data": {
    "primary": {},
    "merged_ids": [
      {}
    ],
    "fields_populated": [
      {}
    ],
    "counts": {}
  }
}

​
Request

Merges fold the duplicates into the primary contact. The primary keeps its UUID; duplicate UUIDs are retired. Non-empty fields on the primary are preserved; missing fields are filled from the duplicates in order. Notes, activities, tasks, emails, documents, and list memberships are re-homed to the primary.

​
Headers

Authorization: Bearer wbk_your_api_key_here
Content-Type: application/json
​
Idempotency-Key
string
Strongly recommended. Same key returns the same result within 24 hours.

​
Body Parameters

​
primary_id
string
required
UUID of the contact that will remain after the merge.
​
duplicate_ids
array
required
UUIDs of contacts to merge into the primary. Maximum 20 per request.
​
overwrite
boolean
default:"false"
When true, non-empty fields on the primary can be overwritten by duplicate values. Defaults to fill-only behavior.
​
dry_run
boolean
default:"false"
When true, the API returns a preview of the merge without making changes.

​
Response

​
data
object
Responses include X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and X-Request-ID. Each merged duplicate emits a contact.merged webhook event. 
curl -X POST \
  https://data.leadlex.com/functions/v1/api-gateway/v1/contacts/merge \
  -H "Authorization: Bearer wbk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "primary_id": "123e4567-e89b-12d3-a456-426614174000",
    "duplicate_ids": ["456e7890-a1b2-34c5-d678-901234567890"]
  }'

​
Example Response

{
  "data": {
    "primary": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "full_name": "Jane Doe",
      "email": "jane@acme.com",
      "phone": "+1-555-0100"
    },
    "merged_ids": ["456e7890-a1b2-34c5-d678-901234567890"],
    "fields_populated": ["phone", "linkedin_url"],
    "counts": {
      "notes": 3,
      "activities": 11,
      "tasks": 2,
      "emails": 18,
      "documents": 1,
      "list_memberships": 4
    }
  }
}

​
Errors

StatusCodeDescription
400validation_errorMore than 20 duplicates, or primary_id appears in duplicate_ids
401invalid_keyInvalid or expired API key
403insufficient_permissionsMissing write:contacts permission
404not_foundPrimary or any duplicate ID was not found
409merge_conflictDuplicates reference each other in a circular chain
429rate_limitedRate limit exceeded