SQL Server / Braze Endpoints / External ID Rename
Back to Collection Items
-- Important: See this note about string length limitations for strings returned by sp_OAMethod calls.
--
CREATE PROCEDURE ChilkatSample
AS
BEGIN
DECLARE @hr int
DECLARE @iTmp0 int
-- Important: Do not use nvarchar(max). See the warning about using nvarchar(max).
DECLARE @sTmp0 nvarchar(4000)
-- This example assumes the Chilkat API to have been previously unlocked.
-- See Global Unlock Sample for sample code.
DECLARE @http int
-- Use "Chilkat_9_5_0.Http" for versions of Chilkat < 10.0.0
EXEC @hr = sp_OACreate 'Chilkat.Http', @http OUT
IF @hr <> 0
BEGIN
PRINT 'Failed to create ActiveX component'
RETURN
END
DECLARE @success int
-- Use this online tool to generate code from sample JSON: Generate Code to Create JSON
-- The following JSON is sent in the request body.
-- {
-- "external_id_renames": [
-- {
-- "current_external_id": "existing_external_id",
-- "new_external_id": "new_external_id"
-- }
-- ]
-- }
DECLARE @json int
-- Use "Chilkat_9_5_0.JsonObject" for versions of Chilkat < 10.0.0
EXEC @hr = sp_OACreate 'Chilkat.JsonObject', @json OUT
EXEC sp_OAMethod @json, 'UpdateString', @success OUT, 'external_id_renames[0].current_external_id', 'existing_external_id'
EXEC sp_OAMethod @json, 'UpdateString', @success OUT, 'external_id_renames[0].new_external_id', 'new_external_id'
EXEC sp_OAMethod @http, 'SetRequestHeader', NULL, 'Content-Type', 'application/json'
-- Adds the "Authorization: Bearer {{api_key}}" header.
EXEC sp_OASetProperty @http, 'AuthToken', '{{api_key}}'
DECLARE @resp int
EXEC sp_OAMethod @http, 'PostJson3', @resp OUT, 'https://rest.iad-01.braze.com/users/external_ids/remove', 'application/json', @json
EXEC sp_OAGetProperty @http, 'LastMethodSuccess', @iTmp0 OUT
IF @iTmp0 = 0
BEGIN
EXEC sp_OAGetProperty @http, 'LastErrorText', @sTmp0 OUT
PRINT @sTmp0
EXEC @hr = sp_OADestroy @http
EXEC @hr = sp_OADestroy @json
RETURN
END
EXEC sp_OAGetProperty @resp, 'StatusCode', @iTmp0 OUT
PRINT @iTmp0
EXEC sp_OAGetProperty @resp, 'BodyStr', @sTmp0 OUT
PRINT @sTmp0
EXEC @hr = sp_OADestroy @resp
EXEC @hr = sp_OADestroy @http
EXEC @hr = sp_OADestroy @json
END
GO
Curl Command
curl -X POST
-H "Content-Type: application/json"
-H "Authorization: Bearer {{api_key}}"
-d '{
"external_id_renames" :
[
{
"current_external_id": "existing_external_id",
"new_external_id" : "new_external_id"
}
]
}'
https://rest.iad-01.braze.com/users/external_ids/remove
Postman Collection Item JSON
{
"name": "External ID Rename",
"request": {
"method": "POST",
"header": [
{
"key": "Content-Type",
"type": "text",
"value": "application/json"
},
{
"key": "Authorization",
"type": "text",
"value": "Bearer {{api_key}}"
}
],
"body": {
"mode": "raw",
"raw": "{\n \"external_id_renames\" : \n [\n {\n \"current_external_id\": \"existing_external_id\",\n \"new_external_id\" : \"new_external_id\"\n }\n ]\n}"
},
"url": {
"raw": "https://{{instance_url}}/users/external_ids/remove",
"protocol": "https",
"host": [
"{{instance_url}}"
],
"path": [
"users",
"external_ids",
"remove"
]
},
"description": "For security purposes, this feature is disabled by default. To enable this feature, please reach out to your Success Manager.\n\nUse this endpoint to “rename” your users’ external IDs. This endpoint sets a new (primary) `external_id` for the user and deprecates their existing `external_id`. This means that the user can be identified by either `external_id` until the deprecated one is removed. The deprecated ID can be removed using the [remove endpoint](https://www.braze.com/docs/api/endpoints/user_data/external_id_migration/post_external_ids_remove). Having multiple external IDs allows for a migration period whereby older versions of your apps still in the wild that use the previous external ID naming schema don’t break. We highly recommend removing deprecated external IDs once your old naming schema is no longer in use.\n\n>You can send up to 50 external IDs per request.<br><br>You will need to create a new [API key](https://www.braze.com/docs/api/api_key/) with permissions for this endpoint.\n\n### Request Parameters\n| Parameter | Required | Data Type | Description |\n| --------- | ---------| --------- | ----------- |\n| `external_id_renames` | Required | Array of external ID rename objects | View request example and the following limitations for structure of external ID rename object |\n\n- The `current_external_id` must be the user’s primary ID, and cannot be a deprecated ID\n- The `new_external_id` must not already be in use as either a primary ID or a deprecated ID\n- The `current_external_id` and `new_external_id` cannot be the same\n\n## Response Body\nThe response will confirm all successful renames, as well as unsuccessful renames with any associated errors. Error messages in the `rename_errors` field will reference the index of the object in the array of the original request.\n\n```\n{\n\n \"message\" : (string) status message,\n \"external_ids\" : (array of successful Rename Operations),\n \"rename_errors\": (array of any <minor error message>)\n\n}\n```\n\nThe `message` field will return `success` for any valid request. More specific errors are captured in the `rename_errors` array. The `message` field returns an error in the case of:\n- Invalid API key\n- Empty `external_id_renames` array\n- `external_id_renames` array with more than 50 objects\n- Rate limit hit (>1,000 requests/minute)\n\n## Frequently Asked Questions\n\n__Does this impact MAU?__\n- No, since the number of users will stay the same, they’ll just have a new `external_id`.\n\n__Does user behavior change historically?__\n- No, since the user is still the same user, and all their historical behavior is still connected to them.\n\n__Can it be run on dev/staging app groups?__\n- Yes. In fact, we highly recommend running a test migration on a staging or development app group, and ensuring everything has gone smoothly before executing on production data.\n\n__Does this consume data points?__\n- This feature does not cost data points.\n\n__What is the recommended deprecation period?__\n- We have no hard limit on how long you can keep deprecated external IDs around, but we highly recommend removing them once there is no longer a need to reference users by the deprecated ID."
},
"response": [
]
}
