Ir al contenido principal
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.

Autorizaciones

Authorizationstringheaderobligatorio

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

Encabezados

Featurebase-Versionenum<string>header

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

Opciones disponibles: 2026-08-19.orbit, 2026-01-01.nova, 2025-12-12.clover
Ejemplo: 2026-08-19.orbit

Cuerpo

application/json
destinationContactIdstringobligatorio

ID of the customer that receives the lead

Ejemplo: 507f1f77bcf86cd799439012
sourceContactIdstringobligatorio

ID of the lead to merge into the destination customer

Ejemplo: 507f1f77bcf86cd799439011

Respuesta

application/json

Success

commentsCreatednumber

Number of comments created

Ejemplo: 0
companiesobject[]

Companies the contact belongs to

customFieldsobject

Custom field values on the contact

descriptionstring

Contact description/bio

Ejemplo:
emailstring | null

Contact email

Ejemplo: john@example.com
idstringobligatorio

Unique identifier

Ejemplo: 676f0f6765bdaa7d7d760f88
lastActivitystring

Last activity ISO timestamp

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

Contact locale

Ejemplo: en
manuallyOptedOutFromChangelogboolean

Whether manually opted out from changelog

Ejemplo: false
namestringobligatorio

Contact display name

Ejemplo: John Steezy
objectenum<string>obligatorio

Object type identifier

Opciones disponibles: contact
Ejemplo: contact
organizationIdstring

Organization ID the contact belongs to

Ejemplo: 5febde12dc56d60012d47db6
postsCreatednumber

Number of posts created

Ejemplo: 0
profilePicturestring | null

Profile picture URL

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

Contact roles

subscribedToChangelogboolean

Whether subscribed to changelog

Ejemplo: true
typeenum<string>obligatorio

Type of contact

Opciones disponibles: customer, lead
Ejemplo: customer
userIdstring

External user ID from SSO

Ejemplo: 676f0f673dbb299c8a4f3057
verifiedboolean

Whether email is verified

Ejemplo: true

¿Aún necesitas ayuda? Pregunta al equipo