The Braze API: Your First /users/track Call, and What Changes at Volume
You've been handed a Braze login and a ticket that says "get signups and purchases into Braze." The REST API does that with one endpoint, /users/track, once you have the right key and the right host. Below is the first working call, then the limits and costs that matter once real traffic hits it, then how to get engagement data back out.
It can message the moment a customer acts, but does it know what they actually did across your systems?
Stuck on Braze? Let's solve it →From no key to a profile update
- 1
Create a REST API key with only the permissions it needs
Settings › APIs and Identifiers › Create API KeyName it after the system that will use it, tick
users.trackand nothing you don't need, and add your servers' IPs to the allowlist. With no IPs listed, the key works from anywhere.Watch for: permissions and allowlisted IPs can't be edited once the key exists. To change them, create a new key, switch over, then retire the old one.
- 2
Copy the REST endpoint for your instance
Each Braze instance has its own host, shown beside your API keys. US-01 is
rest.iad-01.braze.comand EU-01 isrest.fra-01.braze.eu, for example. Calls to the wrong instance fail even with a valid key.Watch for: the SDK endpoint your mobile app uses is a different host. Don't swap one for the other.
- 3
Send the request
POST https://<your-rest-endpoint>/users/trackwithAuthorization: Bearer <key>and a JSON body holdingattributes,eventsandpurchasesarrays. Each object names the user, normally byexternal_id, your own stable user ID.Watch for: if you send a new
external_idtogether with an email or phone that already belongs to a profile, Braze creates a second profile. Settle identity before the first bulk load. - 4
Read the body, not just the status code
A request with some bad objects still comes back as a success, with the rejects listed in an
errorsarray. Malformed JSON returns 400, a bad key 401, a key without permission 403, and too many requests 429 with anX-RateLimit-Retry-Afterheader.Watch for: log every
errorsentry. Otherwise a typo in one attribute name drops data for weeks and nobody notices.
Settle these before you point production traffic at Braze
How many updates fit in one request?
Up to 75 objects combined across attributes, events and purchases. Accounts still on legacy rate limits can send 75 in each array, 225 in total. Batch to that size instead of one call per change.
What's our /users/track rate limit?
It depends on your contract: an hourly limit plus a burst limit every three seconds. The API Usage Dashboard under Settings shows yours. Most other endpoints share a default of 250,000 requests an hour.
Are we sending only what changed?
Each custom attribute sent to /users/track uses a data point, whether or not the value moved. A nightly job resending every field for every user burns allowance for nothing.
Which ID is the real one?
Pick
external_idfrom your own user table and send it from the backend and the SDK alike. Profiles keyed by email in one place and by ID in another are how duplicates start.What happens to a request that gets a 429?
It should wait for the time in
X-RateLimit-Retry-After, then retry, with a queue in front so a spike doesn't drop events. Without a queue, the busiest hour is the one that loses data.
Getting data out: Currents or the export endpoints?
A continuous stream
- Sends message engagement events as they happen, in Avro, to a data warehouse or analytics partner.
- Can also carry customer behavior events and profile changes when those options are switched on.
- Also reaches Segment, mParticle or Tealium, which pass it on to other tools.
- Included in many pro and enterprise packages, with limits set by your entitlements.
Lookups on demand
/users/export/idsreturns the profiles you ask for, by ID.- Accounts set up since August 2024 get 250 export requests a minute.
- Fine for pulling a handful of profiles into a support tool or a script.
- The wrong tool for a full engagement history.
Send opens, clicks and conversions to the warehouse through Currents, and keep the export endpoints for looking up a single user when something else needs them.
Braze next to your CRM and the rest of the stack
Braze holds profiles and events so it can message people. Sales and support still work in a CRM, and they usually want push opens and in-app conversions on the contact record. That flows out through Currents into a warehouse, or through Canvas webhooks into the CRM's API. Braze's own docs show a Salesforce Sales Cloud setup that creates and updates leads that way, and the Salesforce REST API is the receiving end.
The same jobs look different on other platforms. Compare the Iterable API and the Klaviyo API if you're still choosing, see SendGrid webhooks for transactional email events, and Twilio Segment if events should pass through a CDP first. n-frames builds Braze integrations from billing systems, app backends and warehouses, and the return path into whichever CRM your team watches.
Braze API questions, and the ones around it
What is Braze used for?
Sending push, email, SMS and in-app messages across mobile and web, organized in Canvases: visual journeys that start and branch on what each user does. The API is how your own systems tell Braze who those users are and what they did.
Is Braze a CRM?
No. It stores profiles and behavior for messaging, not deals or pipelines. Most teams run Braze beside a CRM and send engagement from one to the other.
Is Braze a CDP?
Braze calls itself a customer engagement platform. It does build unified profiles from events across channels, which overlaps with a CDP, but it doesn't replace one if you need to collect and route data to many tools. Teams with a CDP often feed Braze from it.
How much does Braze cost?
Braze doesn't publish a price list. It quotes by audience size and the channels and features you use, and things like your /users/track limits and Currents entitlements are part of that contract. Ask your account team before designing around a limit.
What are good alternatives to Braze?
Iterable is the closest like-for-like for app-led businesses, and Klaviyo is the usual choice for ecommerce. All three take profiles and events over a REST API, so a well-built sender can be pointed at another platform later without a rewrite.
Can Braze connect to Salesforce?
Yes. Braze documents using webhooks from a Canvas or campaign to create and update leads through Salesforce's API, after a connected app is set up in Salesforce. Getting engagement back onto existing contacts usually goes through Currents and a warehouse, or a small service between the two.
What does Braze integrate with besides Salesforce?
Braze lists technology partners for analytics, data warehouses, CDPs and messaging, and Currents streams engagement to many of them. An internal system or a less common CRM goes through the REST API, which is the part n-frames builds.