Merging customer profiles

You can merge multiple profiles into one.

Important: By default, only profiles with an email are recognized. A profile with a customId but no email is treated as anonymous. To change this behavior, see Setting non-unique emails.

Depending on the scenario, the profiles are merged using one of two endpoints:

If at least one of the profiles is anonymous, use the batch update endpoint.
If both profiles are recognized, use the dedicated endpoint.

At least one profile is anonymous

The table describes how profiles are merged in different combinations.

When an anonymous profile is merged with a recognized one, data such as city, name, etc. is retained from the recognized profile. The UUID of the anonymous customer is saved as a parameter so that existing (or queued for sending at the time of merging) events can be retrieved with that UUID and assigned to the recognized profile.

WARNING: If merging is not possible, any additional data sent with the request is lost. Profile properties are saved to the database only after a successful merge.

Rows are profile A; columns are profile B	email which does not exist in database	email which exists in database	customId which does not exist in database	customId which exists in database, anonymous	customId which exists in database, recognized
UUID (anonymous)	A becomes recognized, receives email¹	A and B are merged¹	A receives customId, remains anonymous	A is merged with B, is anonymous	A is merged with B, is recognized
UUID (recognized)	Existing email is overwritten¹	Conflict, no update²	A receives customId	Conflict, no update²	Conflict, no update²
email does not exist in database	³	³	New profile is created, has email and customId	Email is saved to B, profile becomes recognized	Existing email of B is overwritten
email exists in database	³	³	A receives customId	Conflict, no update²	Conflict, no update²

¹ If customId is configured to be the unique identifier, this method is not recommended.
² API request returns HTTP 202, but the merge does not happen.
³ API request returns HTTP 400, because a JSON object cannot include duplicate keys.

This type of merging also happens automatically when you send an event signed with a workspace JWT that contains the unique identifier of a recognized customer and a UUID of an anonymous one.

Examples

By UUID and customId

Merging is performed by using the batch create/update endpoint.

The request body is an array of objects. Each object is a pair of identifiers of profiles to merge. One profile is identified by UUID, the other by custom ID.

This request merges two anonymous profiles into one:

curl --location --request POST 'https://{SYNERISE_API_BASE_PATH}/v4/clients/batch' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Api-Version: 4.4' \
--header 'Authorization: Bearer eyJh...y4' \
--data-raw '[
   {
      "uuid": "88f40b29-5ba8-437b-ba9d-6d3b99dff80f",
      "customId": "lue42"
   }
]'

Important: If you want to merge more accounts in a single request, send more objects. Each object is treated as a separate pair, so if you send 3 pairs, the result is 3 accounts, not 1 account merged from 6.

By UUID and email

WARNING: If you enabled the non-unique emails feature, this method is NOT recommended.

Merging is performed by using the batch create/update endpoint.

The request body is an array of objects. Each object is a pair of identifiers of profiles to merge. The anonymous profile is identified by UUID, the recognized one by email.

This request merges an anonymous profile (identified by UUID) into a recognized one (identified by email).
The merged profile receives the UUID of the anonymous profile.

curl --location --request POST 'https://{SYNERISE_API_BASE_PATH}/v4/clients/batch' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Api-Version: 4.4' \
--header 'Authorization: Bearer eyJh...y4' \
--data-raw '[
   {
      "uuid": "88f40b29-5ba8-437b-ba9d-6d3b99dff80f",
      "email": "sampleclient@synerise.com"
   }
]'

Both profiles are recognized

Merging recognized customers is done with an endpoint set up specifically for that.

Only custom IDs can be used for this operation.

WARNING:

This operation is irreversible. Use it carefully.
The source accounts are deleted.
Do not merge more than 20 accounts at once.

The following request merges profiles lue42 and mjz84 into a third profile: tla114. lue42 and mjz84 are permanently deleted!

In this operation, the data of the source profiles lue42 and mjz84 (location, agreements, etc.) is lost. The data of the target profile tla114is retained. The events of the source profiles become assigned to the target profile.

curl --location --request POST \
'https://{SYNERISE_API_BASE_PATH}/v4/clients/merge/from/custom-ids/lue42,mjz84/to/custom-id/tla114' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Api-Version: 4.4' \
--header 'Authorization: Bearer eyJh...ey4'