Merge

Get started with the RudderStack Merge API.

  •   2 minute read  

danger
The merge API is deprecated and will be discontinued soon.

RudderStack’s merge API lets you merge different user identities and associate them to a single customer profile in the warehouse.

info
Currently, RudderStack supports 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:

FieldTypePresenceDescription
userIdStringRequired, if anonymousId is not present.The unique user identifier.
anonymousIdStringRequired, if userId is not present.The anonymous ID associated with a user or visitor.
mergePropertiesObjectRequiredThe user properties to be merged and connected to a given user profile.
warning
Either 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:

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.

Questions? Contact us by email or on Slack