---
title: "Merge users"
method: POST
path: "/api/users/merge"
tags: ["users"]
---

# Merge users

`POST /api/users/merge`

Merge two users.<br/><br/>In the request body, specify <code>sourceEmail</code> or <code>sourceUserId</code> (but not both), and <code>destinationEmail</code> or <code>destinationUserId</code> (but not both).<br/><br/>Returns an error if source user does not exist in Iterable. Will update source user if destination user is not found.<br/><br/><b>Rate limit</b>: 50 requests/second, per API key.<br/><br/>Learn about <a href="https://support.iterable.com/hc/articles/29156459027348">identifying users by <code>userId</code> and <code>email</code></a>.

## Request body

- MergeUsersRequest
  - `arrayMerge` ArrayMerge[] — An array of objects, each of which specifies an array field whose contents should be merged during the user merge operation. The objects in this <code>arrayMerge</code> array should only reference custom arrays, not Iterable-managed arrays such as <code>devices</code>.
    - `dedupeBy` string — The name of a top-level field that exists on the objects in the array being merged. The merge operation uses this field for de-duplicating the array merge.<br/><br/>An object in the source array is discarded from the array merge if it contains the field specified by <code>dedupeBy</code>, and if the destination array has an object with the same field and value. (The merge operation considers arrays to be equal if they have the same items, in the same order. Objects are considered equal if they have the same fields and values. Other data types must simply have the same value.)<br/><br/>If you do not provide a <code>dedupeBy</code> field in a given <code>ArrayMerge</code> object, when merging that array Iterable discards source objects that have exact matches in the analogous destination array (same equivalence rules as described above).<br/><br/>Provide this field only when <code>field</code> references an array of objects. Including <code>dedupeBy</code> when merging an array of some other data type (for example, an array of strings), will cause the entire user merge operation to fail.
    - `field` string — The name of a top-level user profile field that contains an array. During the merge operation, the contents of this array on the source profile are merged with the contents of the same array on the destination profile. For details about de-duplicating array merges, see <code>dedupeBy</code>.<br/><br/>If you specify a <code>field</code> whose value is not an array (for example, a single number like <code>age</code>), the merge operation treats that field as an array with a single value. Because of this, after the merge, the value of that field on the destination user profile will be an array containing both of the original values (except if de-duplication affects the result).
  - `destinationEmail` string — An email address that identifies a user profile in Iterable. Provide a <code>destinationEmail</code> or a <code>destinationUserId</code> (but not both), depending on <a href="https://support.iterable.com/hc/articles/29156459027348">how your project identifies users</a>.
  - `destinationUserId` string — A user ID that identifies a user profile in Iterable. Provide a <code>destinationEmail</code> or a <code>destinationUserId</code> (but not both), depending on <a href="https://support.iterable.com/hc/articles/29156459027348">how your project identifies users</a>.
  - `sourceEmail` string — An email address that identifies a user profile in Iterable. Provide a <code>sourceEmail</code> or a <code>sourceUserId</code> (but not both), depending on <a href="https://support.iterable.com/hc/articles/29156459027348">how your project identifies users</a>.
  - `sourceUserId` string — A user ID that identifies a user profile in Iterable. Provide a <code>sourceEmail</code> or a <code>sourceUserId</code> (but not both), depending on <a href="https://support.iterable.com/hc/articles/29156459027348">how your project identifies users</a>.

## Response `200`

successful operation

## Other responses

- `400` — Invalid parameters
- `401` — Invalid API key
- `403` — Merging known user profiles is forbidden with specific API key type. Please use a server-side key.
- `409` — Source or destination user forgotten

---

[API](https://skmtc.net/iterable/apis/iterable-api.md) · [All operations](https://skmtc.net/iterable/apis/iterable-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/iterable/iterable-api/revisions/afaab604b58c/schema)