User Track

post

/users/track

Use this endpoint to record Custom Events, Purchases, and update user profile attributes.

User Track has a base speed limit of 50,000 requests per minute for customers who start with Braze after June 2, 2020. Each request can contain up to 75 events, 75 attribute updates, and 75 purchases. These can belong to different users, that is, each of the 75 events in a request can belong to 75 different users. Please see our page on API limits for details, and reach out to your Customer Success Manager if you need your limit increased.

Please note that 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, check out our data point documentation.

Request Body

1
2
Content-Type: application/json
Authorization: Bearer YOUR_REST_API_KEY
1
2
3
4
5
6
{
   "attributes" : (optional, array of Attributes Object),
   "events" : (optional, array of Event Object),
   "purchases" : (optional, array of Purchase Object),
   "partner" : (optional, string)
}

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

Parameter Required Data Type Description
attributes Optional Array of Attributes Object See User Attributes Object
events Optional Array of Event Object See Events Objects
purchases Optional Array of Purchase Object See Purchase Object
partner Optional String For use by Braze Partners to aid in tracking inbound requests and API usage

Request Components

Note that for each of the request components listed below, one of external_id, user_alias, or braze_id is required.

Example Request Body for Event Tracking

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

You can see this example in action in our Swagger documentation.

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
39
curl --location --request POST 'https://rest.iad-01.braze.com/users/track' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
  "attributes": [ 
    {
      "external_id": "user_id",
      "string_attribute": "sherman",
      "boolean_attribute_1": true,
      "integer_attribute": 25,
      "array_attribute": ["banana", "apple"]
    }
  ],
  "events": [
    {
      "external_id": "user_id",
      "app_id" : "app_identifier",
      "name": "watched_trailer",
      "time": "2013-07-16T19:20:30+1:00"
    }  
  ],
  "purchases": [
    {
      "external_id": "user_id",
      "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"
       } 
     }
  ],
  "partner" : "partner1"
}'

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:

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 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 you will receive the following response:

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

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

Queued Responses

During times of maintenance, Braze might pause the real-time processing of the API. In these situations, the server will return an HTTP Accepted 202 response code and the following body, which indicates that we have received and queued the API call but have not immediately processed it. All scheduled maintenance will be posted to http://status.braze.com ahead of time.

1
2
3
{
  "message" : "queued"
}

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 Code Reason / Cause
400 Bad Request Bad Syntax.
401 Unauthorized Unknown or missing REST API Key.
404 Not Found Unknown REST API Key (if provided).
429 Rate Limited Over rate limit.
5XX Internal server error, you should retry with exponential backoff.

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 you should add the filter – Session Count > 0.

WAS THIS PAGE HELPFUL?
New Stuff!