Skip to navigation

Merge two leads

View as Markdown

Merge the source lead into the destination lead. The source lead’s contacts, opportunities, activities, tasks, custom objects, addresses and custom field values move to the destination lead, and the source lead is then deleted. This can’t be undone.

When both leads have a value, the destination lead’s value is kept. The source lead’s name, status, description and URL are only copied over when the destination lead’s are empty. Contacts and custom objects that match across both leads are combined instead of duplicated.

The merge runs in the background. This request returns as soon as the merge is queued, and both leads get a Lead Merge activity that shows its progress. Neither lead can be merged again until the merge finishes.

Requires the Merge Leads permission. Returns 404 if either lead doesn’t exist, 403 if you don’t have access to either lead, and 400 if both IDs are the same lead, you don’t have permission to merge leads, the merged lead would have too many contacts or custom objects, or either lead is already being merged.

Authentication

AuthorizationBasic
Use your API key as the username and leave the password empty.
OR
AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.
destinationstringRequired>=1 character

ID of the lead to merge into, e.g. lead_6ivpsIOFYDEwCUz8sdftdoWqlKpLSNOAg9glZSLvZEG. This lead is kept, and its values win when both leads have one.

sourcestringRequired>=1 character

ID of the lead to merge from, e.g. lead_JCTqyXSXD42eGO6PlWOe5ase8VRDCpE7ITYti8Th2Ei. Its data moves to the destination lead, and it is then deleted.

Response

Successful response
status"ok"

Always ok. The merge has been queued and runs in the background.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
429
Too Many Requests Error