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:

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.

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 email1 A and B are merged1 A receives customId, remains anonymous A is merged with B, is anonymous A is merged with B, is recognized
UUID (recognized) Existing email is overwritten1 Conflict, no update2 A receives customId Conflict, no update2 Conflict, no update2
email does not exist in database Red checkmark3 Red checkmark3 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 Red checkmark3 Red checkmark3 A receives customId Conflict, no update2 Conflict, no update2

1 If customId is configured to be the unique identifier, this method is not recommended.
2 API request returns HTTP 202, but the merge does not happen.
3 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 business profile 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 'api.synerise.com/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 'api.synerise.com/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"
   }
]'

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.

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 \
'api.synerise.com/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'

😕

We are sorry to hear that

Thank you for helping improve out documentation. If you need help or have any questions, please consider contacting support.

😉

Awesome!

Thank you for helping improve out documentation. If you need help or have any questions, please consider contacting support.

Close modal icon Placeholder alt for modal to satisfy link checker