BrazeEx.Api.UserData (braze_ex v1.0.4)

API calls for all endpoints tagged UserData.

Link to this section Summary

Functions

Create New User Aliases

Use this endpoint to add new user aliases for existing identified users, or to create new unidentified users.

User Delete

This endpoint allows you to delete any user profile by specifying a known user identifier. Up to 50 external_ids, user_aliases, or braze_ids can be included in a single request. Only one of external_ids, user_aliases, or braze_ids can be included in a single request.

Identify Users

Use this endpoint to identify an unidentified (alias-only) user.

User Track

Use this endpoint to record custom events, purchases, and update user profile attributes.

Link to this section Functions

Link to this function

users_alias_new_post(connection, opts \\ [])

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

create-new-user-aliases

Create New User Aliases

Use this endpoint to add new user aliases for existing identified users, or to create new unidentified users.

Note: You can add up to 50 user aliases per request.

Adding a user alias for an existing user requires an external_id to be included in the new user alias object. If the external_id is present in the object but there is no user with that external_id, the alias will not be added to any users. If an external_id is not present, a user will still be created, but will need to be identified later. You can do this using the "Identifying Users" and the users/identify endpoint<br><br>Creating a new alias-only user requires the external_id to be omitted from the new user alias object. Once the user is created, use the /users/track endpoint to associate the alias-only user with attributes, events and purchases, and the /users/identify endpoint to identify the user with an external_id.

rate-limit

Rate limit

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.

request-parameters

Request parameters

ParameterRequiredData TypeDescription
user_aliasesRequiredArray of new user alias objectsSee user alias object.<br><br> For more information on alias_name and alias_label, check out our User Aliases documentation.

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_delete_post(connection, opts \\ [])

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

user-delete

User Delete

This endpoint allows you to delete any user profile by specifying a known user identifier. Up to 50 external_ids, user_aliases, or braze_ids can be included in a single request. Only one of external_ids, user_aliases, or braze_ids can be included in a single request.

Important: Deleting user profiles cannot be undone. It will permanently remove users which may cause discrepancies in your data. Learn more about what happens when you delete a user profile via API in our Help documentation.

rate-limit

Rate limit

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.

request-parameter

Request parameter

ParameterRequiredData TypeDescription
external_idsOptionalArray of stringsExternal identifiers for the users to delete.
user_aliasesOptionalArray of user alias objectUser aliases for the users to delete.
braze_idsOptionalArray of stringsBraze user identifiers for the users to delete.

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_identify_post(connection, opts \\ [])

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

identify-users

Identify Users

Use this endpoint to identify an unidentified (alias-only) user.

Note: You can add up to 50 user aliases per request.

Identifying a user requires an external_id to be included in the aliases_to_identify object. If there is no user with that external_id, the external_id will simply be added to the aliased user’s record, and the user will be considered identified.<br><br>You can associate multiple additional user aliases with a single external_id. When any of such associations are made, only the push tokens and message history associated with the user alias are retained; any attributes, events, or purchases will be “orphaned” and not available on the identified user. One workaround is to export the aliased user’s data before identification using the /users/export/ids endpoint, then re-associate the attributes, events, and purchases with the identified user.

Important: Request fields and their values are case sensitive. Using different cases to reference an external_id will result in duplicate profiles. For example, “abc123” and “ABC123” are two different external_ids.

rate-limit

Rate limit

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.

parameters

Parameters

ParameterRequiredData TypeDescription
aliases_to_identifyRequiredArray of aliases to identify objectSee alias to identify object and user alias object.

aliases-to-identify-object-specification

Aliases to Identify object specification

{
"external_id" : (required, string) see External User ID below,
// external_ids for users that do not exist will return a non-fatal error. 
// See Server Responses for details.
"user_alias" : {
  "alias_name" : (required, string),
  "alias_label" : (required, string)
}
}

parameters-1

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_track_post(connection, opts \\ [])

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

user-track

User Track

Use this endpoint to record custom events, purchases, and update user profile attributes.

Note: Braze processes the data passed via API at face value and customers should only pass deltas (changing data) to minimize unnecessary data point consumption. To read more, refer to Data points.

Customers using the API for server-to-server calls may need to whitelist rest.iad-01.braze.com if they’re behind a firewall.

rate-limit

Rate limit

We apply a base speed limit of 50,000 requests per minute to this endpoint for all customers. Each request to the /users/track endpoint can contain up to 75 events, 75 attribute updates, and 75 purchases. Each component (event, attribute, and purchase arrays), can update up to 75 users each for a max of 225 individual data points. Each update can also belong to the same user for a max of 225 updates to a single user in a request.

See our page on API rate limits for details, and reach out to your customer success manager if you need your limit increased.

request-parameters

Request parameters

Note: For each of the request components listed in the following table, one of external_id, user_alias, or braze_id is required.

ParameterRequiredData TypeDescription
attributesOptionalArray of attributes objectsSee user attributes object
eventsOptionalArray of event objectsSee events object
purchasesOptionalArray of purchase objectsSee purchases object

Keep the following nuances in mind when using the /users/track endpoint:

  • When creating alias-only users through this endpoint, you must explicitly set the _update_existing_only flag to false.
  • Updating the subscription status with this endpoint will both update the user specified by their external_id (such as User1) and update the subscription status of any users with the same email as that user (User1).

user-track-responses

User track responses

Upon using any of the aforementioned API requests you should receive one of the following three general responses:

Successful message

Successful messages will be met with the following response:

{
"message" : "success",
"attributes_processed" : (optional, integer), if attributes are included in the request, this will return an integer of the number of external_ids with attributes that were queued to be processed,
"events_processed" : (optional, integer), if events are included in the request, this will return an integer of the number of events that were queued to be processed,
"purchases_processed" : (optional, integer), if purchases are included in the request, this will return an integer of the number of purchases that were queued to be processed,
}

Successful message with non-fatal errors

If your message is successful but has non-fatal errors such as one invalid event object out of a long list of events, then you will receive the following response:

{
"message" : "success",
"errors" : [
  {
    <minor error message>
  }
]
}

Message with fatal errors

In the case of a success, any data that was not affected by an error in the errors array will still be processed. If your message has a fatal error you will receive the following response:

{
"message" : <fatal error message>,
"errors" : [
  {
    <fatal error message>
  }
]
}

Fatal error response codes

The following status codes and associated error messages will be returned if your request encounters a fatal error. Any of these error codes indicate that no data will be processed.

Error CodeReason / Cause
400 Bad RequestBad Syntax.
401 UnauthorizedUnknown or missing REST API Key.
404 Not FoundUnknown REST API Key (if provided).
429 Rate LimitedOver rate limit.
5XXInternal server error, you should retry with exponential backoff.

If you receive the error “provided external_id is blacklisted and disallowed”, your request may have included a “dummy user”. For more information, refer to Spam blocking.

importing-legacy-user-data

Importing legacy user data

You may submit data through the Braze API for a user who has not yet used your mobile app in order to generate a user profile. If the user subsequently uses the application all information following their identification via the SDK will be merged with the existing user profile you created via the API call. Any user behavior that is recorded anonymously by the SDK prior to identification will be lost upon merging with the existing API-generated user profile.

The segmentation tool will include these users regardless of whether they have engaged with the app. If you want to exclude users uploaded via the User API who have not yet engaged with the app, simply add the filter: Session Count > 0.

making-bulk-updates

Making bulk updates

If you have a use case where you need to make batch updates to the users/track endpoint, we recommend adding the bulk update header so that Braze can properly identify, observe, and route your request.

Refer to the following sample request with the X-Braze-Bulk header:

curl --location --request POST 'https://rest.iad-01.braze.com/users/track' --header 'Content-Type: application/json' --header 'X-Braze-Bulk: true' --header 'Authorization: Bearer YOUR-API-KEY-HERE' --data-raw '{ "attributes": [ ], "events": [ ], "purchases": [ ] }'

Warning: When the X-Braze-Bulk header is present with any value, Braze will consider the request a bulk request. Set the value to true. Currently, setting the value to false does not disable the header—it will still be treated as if it were true.

Use cases

Consider the following use cases where you may use the bulk update header:

  • A daily job where multiple users’ custom attributes are updated via the /users/track endpoint.
  • An ad-hoc user data backfill script which updates user information via the /users/track endpoint.

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