RudderStack's merge
API enables you to merge different user identities and associate them to a single customer profile in the warehouse.
merge
API, refer to the Identity Resolution guide.merge
only for identity resolution in its BigQuery and Snowflake warehouse destinations.Sample payload
A sample payload for the merge
event after removing the common fields is shown below:
{ "type": "merge", "userId": "1hKOmRA4GRlm", "mergeProperties": [{ "type": "email", "value": "alex@example.com" }, { "type": "mobile", "value": "+1-202-555-0146" } ]}
In the above example, type
refers to a unique user identifier like email, phone number, device ID, etc. that can be associated to a given customer profile.
Merge fields
Apart from the Common fields, the merge
call accepts the following fields:
Field | Type | Presence | Description |
---|---|---|---|
userId | String | Required, if anonymousId is not present. | The unique user identifier. |
anonymousId | String | Required, if userId is not present. | The anonymous ID associated with a user or visitor. |
mergeProperties | Object | Required | The user properties to be merged and connected to a given user profile. |
userId
or anonymousId
must be present in the merge
event. Otherwise, you will get a Request neither has anonymousId nor userId error.FAQ
Does RudderStack auto-merge any user identifiers?
Yes, RudderStack auto-merges the following user identifiers by default so you don't need to call the merge
API for them:
userId
andpreviousId
for thealias
calls.userId
andanonymousId
for theidentify
,track
,group
, andscreen
calls.
For merging other user identifiers like device ID, phone number, email ID, etc. you need to use the merge
API.
What is the difference between the alias
and merge
calls?
The alias
call lets you merge two identities of a given user. You can use this call to link the user's previous identifier previousId
with the user's new identifier userId
. You can merge only two user identifiers at a time using alias
.
On the other hand, the merge
API lets you perform identity resolution by stitching together various user identifiers across different touchpoints to a single customer profile. With this call, you can merge any number of user identifiers corresponding to different customer touchpoints like email, phone number, device ID, etc.
Contact us
For more information on the topics covered on this page, email us or start a conversation in our Slack community.