Merge users

Use this endpoint to merge one user into another user.

Up to 50 merges may be specified per request. This endpoint is asynchronous.

Rate limit

For customers who onboarded with Braze on or after September 16, 2021, we apply a shared rate limit of 20,000 requests per minute to this endpoint. This rate limit is shared with the /users/delete, /users/alias/new, /users/identify, and /users/alias/update endpoints, as documented in API rate limits.

Request body

1
2
Content-Type: application/json
Authorization: Bearer YOUR-REST-API-KEY

1
2
3
{
  "merge_updates" : (required, array of objects)
}

Request parameters

Merge_updates behavior

This endpoint will merge any of the following fields found exclusively on the original user to the target user.

• First name
• Last name
• Email
• Gender
• Date of birth
• Phone number
• Time zone
• Home city
• Country
• Language
• Session count (the sum of sessions from both profiles)
• Date of first session (Braze will pick the earlier date of the two dates)
• Date of last session (Braze will pick the later date of the two dates)
• Custom attributes
• Custom event and purchase event data (excluding event properties)
• Custom event and purchase event properties for “X times in Y days” segmentation (where X<=50 and Y<=30)
• Segmentable custom events summary
  • Event count (the sum from both profiles)
  • Event first occurred (Braze will pick the earlier date of the two dates)
  • Event last occurred (Braze will pick the later date of the two dates)
• In-app purchase total in cents (the sum from both profiles)
• Total number of purchases (the sum from both profiles)
• Date of first purchase (Braze will pick the earlier date of the two dates)
• Date of last purchase (Braze will pick the later date of the two dates)
• App summaries
• Last_X_at fields (Braze will update the fields if the orphaned profile fields are more recent)
• Campaign summaries (Braze will pick the most recent date fields)
• Workflow summaries (Braze will pick the most recent date fields)
• Message and message engagement history

Any of the following fields found on one user to the other user:

• Custom event and purchase event count and first date and last date timestamps
  • These merged fields will update “for X events in Y days” filters. For purchase events, these filters include “number of purchases in Y days” and “money spent in last Y days”.

Session data will only be merged if the app exists on both user profiles. For example, if the target user doesn’t have an app summary for “ABCApp” but the original user does, the target user will have the “ABCApp” app summary on their profile after the merge since that original user profile has the app summary.

Nested custom attributes are copied over if the attributes exist on identifier_to_merge, not identifier_to_keep.

Example request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
curl --location --request POST 'https://rest.iad-03.braze.com/users/merge' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-REST-API-KEY' \
--data-raw '{
  "merge_updates": [
    {
      "identifier_to_merge": {
        "external_id": "old-user1"
      },
      "identifier_to_keep": {
        "external_id": "current-user1"
      }
    },
    {
      "identifier_to_merge": {
        "user_alias": {
          "alias_name": "[email protected]",
          "alias_label": "email"
        }
      },
      "identifier_to_keep": {
        "user_alias": {
          "alias_name": "[email protected]",
          "alias_label": "email"
        }
      }
    }
  ]
}'

Response

There are two status code responses for this endpoint: 202 and 400.

Example success response

The status code 202 could return the following response body.

1
2
3
{
  "message": "success"
}

Example error response

The status code 400 could return the following response body. Refer to Troubleshooting for more information about errors you may encounter.

1
2
3
{
  "message": "'merge_updates' must be an array of objects"
}

Troubleshooting

The following table lists possible error messages that may occur.