Merge pull request #4592 from braze-inc/develop

_docs/_api/api_limits.md

@@ -23,7 +23,7 @@ The following table lists specific API rate limits for different request types.
 | --- | --- |
 | [`/users/track`][10] | **Requests:** 50,000 requests per minute. This limit can be increased upon request. Reach out to your customer success manager for more information.<br><br>**Batching:** 75 events, 75 purchases, and 75 attributes per API request. See [Batching User Track requests](#batch-user-track) for more. |
 | [`/users/export/ids`][11] | 2,500 requests per minute. |
-| [`/users/delete`][12]<br>[`/users/alias/new`][13]<br>[`/users/identify`][14] | 20,000 requests per minute, shared between the endpoints. |
+| [`/users/delete`][12]<br>[`/users/alias/new`][13]<br>[`/users/identify`][14]<br>[`/users/merge`][44] | 20,000 requests per minute, shared between the endpoints. |
 | [`/users/external_id/rename`][20] | 1,000 requests per minute. |
 | [`/users/external_id/remove`][21] | 1,000 requests per minute. |
 | [`/events/list`][15] | 1,000 requests per hour, shared with the `/purchases/product_list` endpoint. |
@@ -130,4 +130,5 @@ Under normal conditions, the time for our data eventual consistency to occur is
 [39]: {{site.baseurl}}/api/endpoints/catalogs/catalog_items/synchronous/get_catalog_items_details_bulk/
 [40]: {{site.baseurl}}/api/endpoints/catalogs/catalog_items/synchronous/patch_catalog_item/
 [41]: {{site.baseurl}}/api/endpoints/catalogs/catalog_items/synchronous/post_create_catalog_item/
-[43]: {{site.baseurl}}/get_search_existing_dashboard_user_email/
+[43]: {{site.baseurl}}/get_search_existing_dashboard_user_email/
+[44]: {{site.baseurl}}/api/endpoints/user_data/post_users_merge/

_docs/_api/endpoints/user_data.md

@@ -27,10 +27,13 @@ guide_featured_list:
     fa_icon: fas fa-user-minus
   - name: "POST: Identify a User"
     link: /docs/api/endpoints/user_data/post_user_identify/
-    fa_icon: fas fa-users
+    fa_icon: fas fa-user-circle
   - name: "POST: User Track"
     link: /docs/api/endpoints/user_data/post_user_track/
     fa_icon: fas fa-database
+  - name: "POST: Users Merge"
+    link: /docs/api/endpoints/user_data/post_users_merge/
+    fa_icon: fas fa-users
 
 guide_menu_title: "External ID Migration Endpoints"
 guide_menu_list:

_docs/_api/endpoints/user_data/post_users_merge.md

@@ -0,0 +1,114 @@
+---
+nav_title: "POST: Users Merge"
+article_title: "POST: Users Merge"
+search_tag: Endpoint
+page_order: 4
+layout: api_page
+page_type: reference
+description: "This article outlines details about the Users Merge Braze endpoint."
+
+---
+{% api %}
+# Merge users
+{% apimethod post %}
+/users/merge
+{% endapimethod %}
+
+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
+
+{% multi_lang_include rate_limits.md endpoint='users merge' %}
+
+## Request body
+
+```
+Content-Type: application/json
+Authorization: Bearer YOUR-REST-API-KEY
+```
+
+```json
+{
+  "merge_updates" : (required, array of objects)
+}
+```
+
+## Request parameters
+
+| Parameter | Required | Data Type | Description |
+|---|---|---|---|
+| `merge_updates` | Required | Array | An object array. Each object should contain an `identifier_to_merge` object and an `identifier_to_keep` object, which should each reference a user either by `external_id` or `user_alias`. Both users being merged must be identified using the same method. |
+{: .reset-td-br-1 .reset-td-br-2 .reset-td-br-3 .reset-td-br-4}
+
+## Example request
+
+```
+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": "old-user2@example.com",
+          "alias_label": "email"
+        }
+      },
+      "identifier_to_keep": {
+        "user_alias": {
+          "alias_name": "current-user2@example.com",
+          "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.
+
+```json
+{
+  "message": "success"
+}
+```
+
+### Example error response
+
+The status code `400` could return the following response body. Refer to [Troubleshooting](#troubleshooting) for more information about errors you may encounter.
+
+```json
+{
+  "message": "'merge_updates' must be an array of objects"
+}
+```
+
+## Troubleshooting
+
+The following table lists possible error messages that may occur.
+
+| Error | Troubleshooting |
+| --- |
+| `'merge_updates' must be an array of objects` | Ensure that `merge_updates` is an array of objects. |
+| `a single request may not contain more than 50 merge updates` | You can only specify up to 50 merge updates in a single request. |
+| `identifiers must be objects with an 'external_id' property that is a string, or 'user_alias' property that is an object` | Check the identifiers in your request. |
+| `identifiers must be objects of the same type` | Ensure that the identifier object types match. |
+| `'merge_updates' must only have 'identifier_to_merge' and 'identifier_to_keep'` | Ensure that `merge_updates` only contains the two objects `identifier_to_merge` and `identifier_to_keep`. |
+{: .reset-td-br-1 .reset-td-br-2}
+
+{% endapi %}

_docs/_api/home.md

@@ -90,6 +90,10 @@ glossaries:
     description: Record custom events, purchases, and update user profile attributes.
     tags:
       - User Data
+  - name: <a href='/docs/api/endpoints/user_data/post_users_merge/'>/users/merge</a>
+    description: Merge a user profile into another user.
+    tags:
+      - User Data
   - name: <a href='/docs/api/endpoints/messaging/send_messages/post_send_triggered_campaigns/'>/campaigns/trigger/send</a>
     description: Send immediate, ad-hoc messages to designated users via API-triggered delivery.
       - Send Messages

_includes/rate_limits.md

@@ -46,17 +46,22 @@ For customers who onboarded with Braze on or after August 16, 2021, we apply a r
 <!---/users/delete-->
 
 {% elsif include.endpoint == "users delete" %}
-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/alias/new` and `/users/identify` endpoints, as documented in [API rate limits]({{site.baseurl}}/api/api_limits/).
+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/alias/new`, `/users/identify`, and `/users/merge` endpoints, as documented in [API rate limits]({{site.baseurl}}/api/api_limits/).
 
 <!---/users/alias/new-->
 
 {% elsif include.endpoint == "users alias new" %}
-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` and `/users/identify` endpoints, as documented in [API rate limits]({{site.baseurl}}/api/api_limits/).
+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/identify`, and `/users/merge` endpoints, as documented in [API rate limits]({{site.baseurl}}/api/api_limits/).
 
 <!---/users/identify-->
 
 {% elsif include.endpoint == "users identify" %}
-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` and `/users/alias/new` endpoints, as documented in [API rate limits]({{site.baseurl}}/api/api_limits/).
+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`, and `/users/merge` endpoints, as documented in [API rate limits]({{site.baseurl}}/api/api_limits/).
+
+<!---/users/merge-->
+
+{% elsif include.endpoint == "users merge" %}
+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`, and `/users/identify` endpoints, as documented in [API rate limits]({{site.baseurl}}/api/api_limits/).
 
 <!---/events/list-->