# Braze Documentation Braze is a comprehensive customer engagement platform that enables businesses to deliver personalized messaging campaigns across multiple channels including push notifications, email, SMS, in-app messages, and content cards. The platform provides robust REST APIs for server-side integration and native SDKs for iOS, Android, Web, and various cross-platform frameworks like React Native, Flutter, and Unity. This documentation repository contains user guides, developer integration documentation, API reference, partner integrations, and release notes for the Braze platform. It serves as the source for [braze.com/docs](https://www.braze.com/docs) and covers everything from initial SDK setup to advanced campaign orchestration, data management, and analytics. ## REST API Endpoints ### Track Users - Create and Update User Profiles The `/users/track` endpoint records custom events, purchases, and updates user profile attributes. This is the primary endpoint for server-side user data management with support for batching up to 75 events, 75 purchases, and 75 attributes per request. ```bash 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_123", "email": "user@example.com", "first_name": "John", "custom_attribute": "premium_member", "subscription_groups": [{ "subscription_group_id": "subscription_group_identifier", "subscription_state": "subscribed" }] } ], "events": [ { "external_id": "user_123", "app_id": "your_app_identifier", "name": "completed_purchase", "time": "2024-01-15T10:30:00+00:00", "properties": { "product_name": "Premium Plan", "price": 99.99 } } ], "purchases": [ { "external_id": "user_123", "app_id": "your_app_identifier", "product_id": "premium_subscription", "currency": "USD", "price": 99.99, "quantity": 1, "time": "2024-01-15T10:30:00Z" } ] }' # Response: # { # "message": "success", # "attributes_processed": 1, # "events_processed": 1, # "purchases_processed": 1 # } ``` ### Send Messages Immediately The `/messages/send` endpoint sends immediate messages to designated users using the Braze API. Messages can target specific users by external ID, user alias, email, or segment membership with support for multiple messaging channels in a single request. ```bash curl --location --request POST 'https://rest.iad-01.braze.com/messages/send' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_REST_API_KEY' \ --data-raw '{ "external_user_ids": ["user_123", "user_456"], "recipient_subscription_state": "subscribed", "campaign_id": "campaign_identifier", "messages": { "email": { "app_id": "your_app_id", "from": "Company ", "subject": "Your Order Confirmation", "body": "Thank you for your order!" }, "apple_push": { "alert": "Your order has been confirmed!", "badge": 1, "extra": { "order_id": "12345" } } } }' # Response: # { # "dispatch_id": "dispatch_identifier", # "message": "success" # } ``` ### Export User Profile by Identifier The `/users/export/ids` endpoint exports data from user profiles by specifying user identifiers. Supports up to 50 external IDs or user aliases per request with configurable field selection for optimized response times. ```bash curl --location --request POST 'https://rest.iad-01.braze.com/users/export/ids' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_REST_API_KEY' \ --data-raw '{ "external_ids": ["user_123"], "fields_to_export": ["first_name", "email", "custom_attributes", "purchases", "devices"] }' # Response: # { # "message": "success", # "users": [ # { # "external_id": "user_123", # "first_name": "John", # "email": "user@example.com", # "custom_attributes": { # "loyalty_points": 500, # "membership_tier": "gold" # }, # "purchases": [ # { # "name": "premium_subscription", # "first": "2024-01-01T00:00:00Z", # "last": "2024-01-15T10:30:00Z", # "count": 3 # } # ], # "devices": [ # { # "model": "iPhone 14", # "os": "iOS 17.0" # } # ] # } # ] # } ``` ### Send API-Triggered Campaign The `/campaigns/trigger/send` endpoint triggers existing campaigns created in the Braze dashboard with API-triggered delivery. Supports personalization through trigger properties and can target specific users or Connected Audiences. ```bash curl --location --request POST 'https://rest.iad-01.braze.com/campaigns/trigger/send' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_REST_API_KEY' \ --data-raw '{ "campaign_id": "campaign_identifier", "trigger_properties": { "product_name": "Premium Subscription", "discount_code": "SAVE20" }, "recipients": [ { "external_user_id": "user_123", "trigger_properties": { "first_name": "John" }, "attributes": { "last_campaign_sent": "2024-01-15" } } ], "attachments": [ { "file_name": "invoice", "url": "https://example.com/invoices/12345.pdf" } ] }' # Response: # { # "dispatch_id": "dispatch_identifier", # "message": "success" # } ``` ### Create Catalog The `/catalogs` endpoint creates catalogs for storing product, content, or other structured data that can be referenced in Braze campaigns. Catalogs support various field types including strings, numbers, booleans, objects, arrays, and timestamps. ```bash curl --location --request POST 'https://rest.iad-01.braze.com/catalogs' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_REST_API_KEY' \ --data-raw '{ "catalogs": [ { "name": "products", "description": "Product catalog for recommendations", "fields": [ {"name": "id", "type": "string"}, {"name": "name", "type": "string"}, {"name": "price", "type": "number"}, {"name": "category", "type": "string"}, {"name": "in_stock", "type": "boolean"}, {"name": "metadata", "type": "object"}, {"name": "tags", "type": "array"}, {"name": "created_at", "type": "time"} ] } ] }' # Response: # { # "catalogs": [ # { # "name": "products", # "description": "Product catalog for recommendations", # "fields": [...], # "num_items": 0, # "updated_at": "2024-01-15T10:00:00.000+00:00" # } # ], # "message": "success" # } ``` ### Update Subscription Group Status The `/subscription/status/set` endpoint batch updates subscription group status for up to 50 users. Supports both email and SMS/RCS subscription groups with external ID, email, or phone number identification. ```bash # Email subscription update curl --location --request POST 'https://rest.iad-01.braze.com/subscription/status/set' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_REST_API_KEY' \ --data-raw '{ "subscription_group_id": "email_newsletter_group_id", "subscription_state": "subscribed", "external_id": "user_123", "email": ["user@example.com"] }' # SMS subscription update curl --location --request POST 'https://rest.iad-01.braze.com/subscription/status/set' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_REST_API_KEY' \ --data-raw '{ "subscription_group_id": "sms_alerts_group_id", "subscription_state": "subscribed", "external_id": "user_123", "phone": ["+12025551234"] }' # Response: # { # "message": "success" # } ``` ## SDK Integration ### Set User IDs The `changeUser()` method identifies users across devices and platforms. Call this method after user login to enable cross-device tracking, targeted messaging, and user data import through the REST API. ```javascript // Web SDK braze.changeUser("user_123"); // React Native Braze.changeUser("user_123"); ``` ```java // Android (Java) Braze.getInstance(context).changeUser("user_123"); ``` ```kotlin // Android (Kotlin) Braze.getInstance(context).changeUser("user_123") ``` ```swift // iOS (Swift) AppDelegate.braze?.changeUser(userId: "user_123") ``` ```objc // iOS (Objective-C) [AppDelegate.braze changeUser:@"user_123"]; ``` ```dart // Flutter braze.changeUser("user_123"); ``` ### Log Custom Events Custom events track user actions and behaviors for segmentation, campaign triggering, and analytics. Events support metadata properties including strings, numbers, booleans, dates, arrays, and nested JSON objects. ```javascript // Web SDK - Basic event braze.logCustomEvent("completed_tutorial"); // Web SDK - Event with properties braze.logCustomEvent("product_viewed", { product_id: "SKU_12345", product_name: "Wireless Headphones", price: 149.99, category: "Electronics", viewed_at: new Date(), tags: ["audio", "wireless", "featured"] }); ``` ```java // Android (Java) Braze.getInstance(context).logCustomEvent("product_viewed", new BrazeProperties(new JSONObject() .put("product_id", "SKU_12345") .put("product_name", "Wireless Headphones") .put("price", 149.99) .put("category", "Electronics") )); ``` ```swift // iOS (Swift) AppDelegate.braze?.logCustomEvent( name: "product_viewed", properties: [ "product_id": "SKU_12345", "product_name": "Wireless Headphones", "price": 149.99, "category": "Electronics" ] ) ``` ```dart // Flutter braze.logCustomEvent('product_viewed', properties: { 'product_id': 'SKU_12345', 'product_name': 'Wireless Headphones', 'price': 149.99, }); ``` ### Add User Aliases User aliases provide alternative identifiers for users, enabling cross-platform tracking with third-party systems. An alias consists of a name (the identifier) and a label (the identifier type). ```javascript // Web SDK braze.getUser().addAlias("support_user_987654", "zendesk_id"); braze.getUser().addAlias("amplitude_abc123", "amplitude_id"); ``` ```java // Android (Java) Braze.getInstance(context).getCurrentUser().addAlias("support_user_987654", "zendesk_id"); ``` ```kotlin // Android (Kotlin) Braze.getInstance(context).currentUser?.addAlias("support_user_987654", "zendesk_id") ``` ```swift // iOS (Swift) Appboy.sharedInstance()?.user.addAlias("support_user_987654", "zendesk_id") ``` ## Rate Limits and Best Practices The Braze API enforces rate limits to ensure system stability. Key limits include: `/users/track` at 3,000 requests per 3 seconds with 75 items per batch; `/users/export/ids` at 250 requests per minute (or 2,500 for legacy accounts); messaging endpoints at 250,000 requests per hour shared across endpoints. Monitor rate limit headers (`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`) in API responses to manage request rates programmatically. Braze supports comprehensive multi-channel campaign orchestration through Campaigns and Canvas (visual workflow builder), with integrations for major data warehouses, CDPs, and marketing tools. The platform provides real-time analytics, A/B testing, intelligent delivery optimization, and predictive capabilities powered by machine learning. For optimal integration, batch API requests where possible, implement proper error handling for rate limit responses (HTTP 429), and maintain a 5-minute delay between dependent endpoint calls to ensure data consistency.