BrazeEx.Api.UserDataExternalIDMigration (braze_ex v1.0.4)

API calls for all endpoints tagged UserDataExternalIDMigration.

Link to this section Summary

Functions

External ID Remove

Note: For security purposes, this feature is disabled by default. To enable this feature, reach out to your customer success manager.

External ID Rename

Note: For security purposes, this feature is disabled by default. To enable this feature, reach out to your customer success manager.

Link to this section Functions

Link to this function

users_external_ids_remove_post(connection, opts \\ [])

@spec users_external_ids_remove_post(
  Tesla.Env.client(),
  keyword()
) :: {:ok, nil} | {:error, Tesla.Env.t()}

external-id-remove

External ID Remove

Note: For security purposes, this feature is disabled by default. To enable this feature, reach out to your customer success manager.

Use this endpoint to remove your users' old deprecated external IDs. This endpoint completely removes the deprecated ID and cannot be undone.

You can send up to 50 external IDs per request.

You will need to create a new API key with permissions for this endpoint.

rate-limit

Rate limit

We apply a rate limit of 1,000 requests per minute to this endpoint, as documented in API rate limits.

request-parameters

Request parameters

ParameterRequiredData TypeDescription
external_idsRequiredArray of stringsExternal identifiers for the users to remove

Important: Only deprecated IDs can be removed; attempting to remove a primary external ID will result in an error.

response

Response

The response will confirm all successful removals, as well as unsuccessful removals with the associated errors. Error messages in the removal_errors field will reference the index in the array of the original request.

{
"message" : (string) status message,
"removed_ids" : (array of successful Remove Operations),
"removal_errors": (array of any )
}

The message field will return success for any valid request. More specific errors are captured in the removal_errors array. The message field returns an error in the case of:

  • Invalid API key
  • Empty external_ids array
  • external_ids array with more than 50 items
  • Rate limit hit (>1,000 requests/minute)

parameters

Parameters

  • connection (BrazeEx.Connection): Connection to server
  • opts (keyword): Optional parameters
    • :content_type (String.t):
    • :authorization (String.t):
    • :body (String.t):

returns

Returns

  • {:ok, nil} on success
  • {:error, Tesla.Env.t} on failure
Link to this function

users_external_ids_rename_post(connection, opts \\ [])

@spec users_external_ids_rename_post(
  Tesla.Env.client(),
  keyword()
) :: {:ok, nil} | {:error, Tesla.Env.t()}

external-id-rename

External ID Rename

Note: For security purposes, this feature is disabled by default. To enable this feature, reach out to your customer success manager.

Use 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 External ID remove endpoint. 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.

Note: You can send up to 50 external IDs per request.

You will need to create a new API key with permissions for this endpoint.

rate-limit

Rate limit

We apply a rate limit of 1,000 requests per minute to this endpoint, as documented in API rate limits.

request-parameters

Request parameters

ParameterRequiredData TypeDescription
external_id_renamesRequiredArray of external ID rename objectsView request example and the following limitations for structure of external ID rename object
  • The current_external_id must be the user’s primary ID, and cannot be a deprecated ID
  • The new_external_id must not already be in use as either a primary ID or a deprecated ID
  • The current_external_id and new_external_id cannot be the same

response

Response

The 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.

{
"message" : (string) status message,
"external_ids" : (array of successful Rename Operations),
"rename_errors": (array of any )
}

The 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:

  • Invalid API key
  • Empty external_id_renames array
  • external_id_renames array with more than 50 objects
  • Rate limit hit (>1,000 requests/minute)

frequently-asked-questions

Frequently Asked Questions

Does this impact MAU?
No, since the number of users will stay the same, they’ll just have a new external_id.

Does user behavior change historically?
No, since the user is still the same user, and all their historical behavior is still connected to them.

Can it be run on dev/staging app groups?
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.

Does this consume data points?
This feature does not cost data points.

What is the recommended deprecation period?
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.

parameters

Parameters

  • connection (BrazeEx.Connection): Connection to server
  • opts (keyword): Optional parameters
    • :content_type (String.t):
    • :authorization (String.t):
    • :body (String.t):

returns

Returns

  • {:ok, nil} on success
  • {:error, Tesla.Env.t} on failure