User track

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

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 body

1
2
Content-Type: application/json
Authorization: Bearer YOUR-REST-API-KEY

1
2
3
4
5
{
   "attributes" : (optional, array of attributes object),
   "events" : (optional, array of event object),
   "purchases" : (optional, array of purchase object),
}

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

Request parameters

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

Example request body for event tracking

1
2
3
4
5
6
7
8
9
{
  "events": [
    {
      "external_id": "string",
      "name": "string",
      "time": "string"
    }
  ]
}

Example request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
curl --location --request POST 'https://rest.iad-01.braze.com/users/track' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-API-KEY-HERE' \
--data-raw '{
  "attributes": [ 
  {
    "external_id":"user_identifier",
      "string_attribute": "fruit",
      "boolean_attribute_1": true,
      "integer_attribute": 25,
      "array_attribute": ["banana", "apple"]
    }
    ],
    "events": [
    {
      "external_id": "user_identifier",
      "app_id" : "app_identifier",
      "name": "watched_trailer",
      "time": "2013-07-16T19:20:30+1:00"
    }  
   ],
  "purchases": [
     {
      "external_id": "user_identifier",
      "app_id": "app_identifier",
      "product_id": "product_name",
      "currency": "USD",
      "price": 12.12,
      "quantity": 6,
      "time": "2017-05-12T18:47:12Z",
      "properties": {
         "integer_property": 3,
         "string_property": "Russell",
         "date_property": "2014-02-02T00:00:00Z"
       } 
     }
  ]
}'

Responses

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

1
2
3
4
5
6
{
  "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:

1
2
3
4
5
6
7
8
{
  "message" : "success",
  "errors" : [
    {
      <minor error message>
    }
  ]
}

For success messages, any data that was not affected by an error in the errors array will still be processed.

Message with fatal errors

If your message has a fatal error, you will receive the following response:

1
2
3
4
5
6
7
8
{
  "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. The following error codes indicate that no data will be processed.

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

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

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:

1
2
3
4
5
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": [ ] }'

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.