Skip to main content
Contacts

Merge a lead into a customer

Merges a lead into a customer. Use it when a lead becomes a user of your product.

POST
/v2/contacts/merge

The source contact must be a lead and the destination contact must be a customer. Both must belong to the authenticated organization.

When the merge completes:

  • The lead's conversations move to the customer.
  • Empty customer fields, such as name, phone, locale, custom fields, and companies, are filled from the lead. Existing customer values are kept.
  • The lead's email is kept on the customer as a merged lead email, so a later "type": "lead" upsert with that email returns 409.
  • The lead is archived: its email is removed and it no longer appears in contact search. GET /v2/contacts/{id} and GET /v2/contacts?contactType=lead still return it, without an email.

Retrying the same source and destination after a successful merge is safe and returns the customer without merging again. A lead can be merged into one customer only.

The response contains the updated destination customer.

Example Request

{
  "sourceContactId": "507f1f77bcf86cd799439011",
  "destinationContactId": "507f1f77bcf86cd799439012"
}

Version Availability

This endpoint is available in API version 2026-01-01.nova and newer.

Authorizations

Authorizationstringheaderrequired

API key as Bearer token. Use: Authorization: Bearer sk_...

Headers

Featurebase-Versionenum<string>header

API version for this request. Defaults to your organization's configured API version if not specified.

Available options: 2026-08-19.orbit, 2026-01-01.nova, 2025-12-12.clover
Example: 2026-08-19.orbit

Body

application/json
destinationContactIdstringrequired

ID of the customer that receives the lead

Example: 507f1f77bcf86cd799439012
sourceContactIdstringrequired

ID of the lead to merge into the destination customer

Example: 507f1f77bcf86cd799439011

Response

application/json

Success

commentsCreatednumber

Number of comments created

Example: 0
companiesobject[]

Companies the contact belongs to

customFieldsobject

Custom field values on the contact

descriptionstring

Contact description/bio

Example:
emailstring | null

Contact email

Example: john@example.com
idstringrequired

Unique identifier

Example: 676f0f6765bdaa7d7d760f88
lastActivitystring

Last activity ISO timestamp

Example: 2025-01-03T21:42:30.181Z
localestring

Contact locale

Example: en
manuallyOptedOutFromChangelogboolean

Whether manually opted out from changelog

Example: false
namestringrequired

Contact display name

Example: John Steezy
objectenum<string>required

Object type identifier

Available options: contact
Example: contact
organizationIdstring

Organization ID the contact belongs to

Example: 5febde12dc56d60012d47db6
postsCreatednumber

Number of posts created

Example: 0
profilePicturestring | null

Profile picture URL

Example: https://fb-usercontent.fra1.cdn.digitaloceanspaces.com/anon_23.png
rolesstring[]

Contact roles

subscribedToChangelogboolean

Whether subscribed to changelog

Example: true
typeenum<string>required

Type of contact

Available options: customer, lead
Example: customer
userIdstring

External user ID from SSO

Example: 676f0f673dbb299c8a4f3057
verifiedboolean

Whether email is verified

Example: true

Still need help? Ask the team