Data Objects Endpoints
Use these endpoints to list data object types, manage data object records, and manage object and user relationships.

Data Objects is generally available, but your workspace must be provisioned for Accounts before you can use these endpoints. To request provisioning, go to Data Settings > Accounts and complete the questionnaire. After provisioning is complete, the Data Objects API key permissions appear on Settings > API Keys. For details, see Enable Accounts.
Type endpoints
Object endpoints
Object relationship endpoints
User relationship endpoints
Base URL and authentication
Use your workspace REST endpoint and send Authorization: Bearer YOUR_REST_API_KEY. This section explains where Data Objects endpoints are hosted and how requests are authenticated.
- For endpoint hosts, refer to Braze API overview.
- All request and response payloads are JSON.
- Requests are scoped to the workspace that owns the API key.
- If the key has an IP allowlist, non-allowlisted IP addresses return
403.
API key permissions
This section maps each endpoint to its required permission so you can scope API keys safely.
| Permission | Endpoint group |
|---|---|
data_objects.read |
Type and object reads, and object relationship reads |
data_objects.create |
Object create |
data_objects.update |
Object replace and update |
data_objects.delete |
Object delete |
data_objects.user_relationships.read |
User relationship reads |
data_objects.user_relationships.create |
User relationship create |
data_objects.user_relationships.update |
User relationship replace and update |
data_objects.user_relationships.delete |
User relationship delete |
data_objects.object_relationships.create |
Object relationship create |
data_objects.object_relationships.update |
Object relationship replace and update |
data_objects.object_relationships.delete |
Object relationship delete |
data_objects.bulk_upsert |
Object bulk create or replace |
data_objects.bulk_delete |
Object bulk delete |
data_objects.object_relationships.bulk_upsert |
Object relationship bulk create or replace |
data_objects.object_relationships.bulk_delete |
Object relationship bulk delete |
data_objects.user_relationships.bulk_upsert |
User relationship bulk create or replace |
data_objects.user_relationships.bulk_delete |
User relationship bulk delete |

Object relationship reads use data_objects.read. There is no data_objects.object_relationships.read permission.
The bulk endpoints use their own permissions, and upsert and delete are separate permissions. The single-record permissions, such as data_objects.create, don’t grant access to the bulk endpoints.
Rate limits
This section explains default request quotas and response headers for both read and write traffic.
| Bucket | Default limit |
|---|---|
| Data Objects reads | 1000 requests per minute |
| Data Objects writes | 1000 requests per minute |
| Data Objects bulk writes | 1000 requests per minute, shared across the six bulk endpoints and with Cloud Data Ingestion syncs of data objects |
The bulk write limit applies per workspace and is separate from the single-record write limit.
Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.
For throttled requests, Braze returns 429 and an error payload with id and message.
{
"errors": [
{
"id": "rate-limit-exceeded",
"message": "You have exceeded your limit of 1000 requests per minute."
}
]
}
Product limits
This section lists the limits Braze enforces for Data Objects and what to expect when you reach one. For how these limits apply to account records, see Account objects limits.
Count limits
These limits apply to your company as a whole unless noted otherwise. These are starting capacities. If you need more records or a higher limit, contact your Braze account team to request an increase.
| Limit | Default value |
|---|---|
| Data object records per company (across all workspaces) | 50,000 |
| Fields per data object type | 500 |
| Data objects linked to one user | 1,000 |
| Users linked to one data object | 10,000 |
| Object relationships for one data object | 1,000 |
Field and value limits
These limits are fixed for all companies.
| Limit | Value |
|---|---|
| Fields per relationship type (user relationships and object relationships) | 25. Relationship fields don’t count toward the fields per data object type limit. |
| Attribute value length | 255 characters |
| Date fields | RFC 3339 date-time strings that include a time and time zone, such as 2026-11-03T00:00:00Z. Braze rejects date-only values such as 2026-11-03. For details, see Date field format. |
object_id length and format |
250 characters. Letters, numbers, hyphens, and underscores only. |
| Field name length and format | 250 characters. Letters, numbers, and underscores only, and can’t start with an underscore. |
| Reserved field names | id, external_id, object_id, and display_name can’t be used as custom field names. |
Date field format
Date fields accept only RFC 3339 date-time strings that include both a time and a time zone. Braze requires the full value so that it never has to guess a time or time zone. If your source stores date-only values, such as renewal or contract dates in your data warehouse, convert them before you send them, for example in your warehouse transform.
| Value | Result |
|---|---|
2026-11-03T00:00:00Z |
Accepted |
2026-11-03T00:00:00-05:00 |
Accepted |
2026-11-03 |
Rejected because it has no time or time zone |
2026-11-03T00:00:00 |
Rejected because it has no time zone |
This format applies to date fields on data objects, user relationships, and object relationships. How Braze reports a rejected value depends on how you send it:
- The single-record create, replace, and update endpoints return
400. If more than one attribute is invalid, the error names only the first one. - The bulk upsert endpoints accept the request with
202, then record adata-object-schema-mismatchprocessing failure for the record, such asattributes: renewal_date is not valid for its field. - Cloud Data Ingestion syncs use the same processing as the bulk endpoints, so Braze doesn’t apply a row with a date-only value, and the failure appears in the sync logs.
For example, a single-record request that sends 2026-11-03 for a renewal_date date field returns this 400 response:
{
"error": "Validation failed: Attrs do not conform to field definitions: The property '#/renewal_date' must be a valid RFC3339 date/time string"
}
What happens when you reach a limit
A request that would exceed a count limit returns 422 with an error id that identifies the limit:
{
"errors": [
{
"id": "data-object-record-limit-exceeded",
"message": "This company has reached its data object record limit"
}
]
}
| Limit | Error id |
|---|---|
| Data object records per company | data-object-record-limit-exceeded |
| Fields per data object type | data-object-field-limit-exceeded |
| Fields per relationship type | data-object-field-limit-exceeded |
| Data objects linked to one user | data-objects-per-user-limit-exceeded |
| Users linked to one data object | users-per-data-object-limit-exceeded |
| Object relationships for one data object | data-object-relationship-limit-exceeded |
Your existing records and relationships stay in place—only the request that would exceed the limit is rejected. To make room under a limit, delete records you no longer need or remove relationships you no longer use. To raise a count limit, contact your Braze account team.
Requests that fail validation, such as an object_id or attribute value that’s too long, return 400. Requests over the rate limit return 429.
Core concepts
This section defines the key identifiers used across all Data Objects endpoints.
type_name: The data object type machine name, unique within a workspace.object_id: Your object identifier, unique within a type.user: The user on a user relationship write request, identified by exactly one ofexternal_id,braze_id,alias,email, orphone.attributes: Field-name-keyed object or relationship data validated against the configured schema.
How relationships work
This section explains relationship types, relationship edges, and anchor behavior before you use the endpoint reference pages.
Relationship model overview
Use this diagram to see how types, records, and relationships fit together, and what linking them lets you do in Braze. You define the types in the dashboard, then write the records and the links between them through these endpoints.
%%{init: {"flowchart": {"wrappingWidth": 400}} }%%
flowchart LR
subgraph define["Set up in the dashboard"]
objtype["Data object types define<br/>the fields a record has"]
reltype["Relationship types determine<br/>which links are allowed"]
end
subgraph write["Write with the API"]
person["A person you<br/>send messages to"]
record["A business record<br/>they belong to"]
related["Another record<br/>connected to it"]
person -- "A user relationship links<br/>a person to a record" --> record
record -- "An object relationship links<br/>one record to another" --> related
end
subgraph unlock["What it unlocks"]
segment["Segment people by the<br/>records they belong to"]
liquid["Personalize messages with<br/>data from those records"]
end
define -- "decides what you<br/>are allowed to link" --> write
write -- "makes these<br/>possible" --> unlock
Types and edges are separate
- Relationship types define which links are valid and are managed in the dashboard.
- Relationship edges are the actual links between records and are created, updated, and deleted through these API endpoints.
- Before writing relationships, list valid
rel_kindvalues with:GET /data_objects/types/{type_name}/user_relationship_typesGET /data_objects/types/{type_name}/object_relationship_types
Why object relationships require related_type_name
rel_kindis not globally unique across all object type pairs. For example,rel_kindcan besubaccountfor one pair of object types andpartner_accountfor another.- Object relationship writes therefore require both
rel_kindandrelated_type_nameto identify the intended relationship type along with the other type of object in the association. - If the
related_type_namedoes not match the relationship type for thatrel_kind, the request returns400.
anchor controls relationship direction
Object relationships are directional. The URL object is interpreted based on anchor.
anchor |
URL object role | Related object key in responses |
|---|---|---|
source (default) |
From side (outgoing edge) | to_data_object |
target |
To side (incoming edge) | from_data_object |
Creating the same edge from the opposite anchor perspective still targets one underlying relationship. A second create call for the same edge returns 409 (duplicate-object-relationship).
Path asymmetry for user relationships
User relationship reads and writes intentionally use different endpoint paths:
- Read:
GET /data_objects/objects/{type_name}/{object_id}/user_relationships - Write:
POST|PUT|PATCH|DELETE /data_objects/objects/{type_name}/{object_id}/users
Relationship attributes are separate from object attributes
- Relationship endpoints return edge-level attributes in the top-level
attributesfield. - Object attributes stay nested under
to_data_objectorfrom_data_object. PUTreplaces relationshipattributes, andPATCHmerges relationshipattributes.
Worked example
This example shows a common account workflow:
- Create
account/acct-123. - Create
account/acct-456as a child account. - Link a user to
acct-123withrel_kind: account_user. - Link
acct-123toacct-456withrel_kind: subaccount.
To read back the links:
GET /data_objects/objects/account/acct-123/user_relationshipsfor linked usersGET /data_objects/objects/account/acct-123/object_relationshipsfor outgoing object linksGET /data_objects/objects/account/acct-456/object_relationships?anchor=targetfor incoming object links

The DELETE endpoints for object relationships and user relationships require a JSON request body.
Bulk endpoints
Use the bulk endpoints to sync data objects, object relationships, and user relationships from your own systems in batches. Each request creates, replaces, or deletes up to 50 records, and Braze processes the batch in the background.
| Method | Endpoint | Purpose |
|---|---|---|
PUT |
/data_objects/objects |
Create or replace up to 50 data objects, of any mix of types |
DELETE |
/data_objects/objects |
Delete up to 50 data objects, of any mix of types |
PUT |
/data_objects/object_relationships |
Create or replace up to 50 object-to-object relationships |
DELETE |
/data_objects/object_relationships |
Delete up to 50 object-to-object relationships |
PUT |
/data_objects/user_relationships |
Create or replace up to 50 user-to-object relationships |
DELETE |
/data_objects/user_relationships |
Delete up to 50 user-to-object relationships |
When to use the bulk endpoints
Use the bulk endpoints when you sync many records from your own systems and don’t need each change applied before the response returns. Use the single-record endpoints when you need the change visible right away, when you need to read records, or when you want to update only some of a record’s attributes with PATCH.
The bulk endpoints differ from the single-record endpoints in these ways:
- Processing is asynchronous. A
202response means Braze accepted and queued the batch, not that it applied the records. Braze checks whether types, relationship types, objects, and users exist, and whether attributes match the type’s fields, when it processes the batch. A request that returns202can still produce failures for individual records later. - Validation is all-or-nothing. If any record in a request fails validation, Braze rejects the whole request with
400, stores nothing, and lists every error. - Records are ordered by receipt time. Braze stamps every record with the time it received the request, so don’t send
updated_at. When two requests change the same record, the one Braze received later wins. - Records can wait on dependencies. A delete of an object or relationship that doesn’t exist yet, and a relationship whose object or user doesn’t exist yet, waits instead of failing right away. Braze retries for about 40 hours (10 attempts). An object upsert never waits.
- The bulk endpoints use their own API key permissions and share a rate limit of 1,000 requests per minute per workspace.
- The bulk endpoints never create data object types. Every
type_namemust already exist.
The product limits apply to the bulk endpoints in the same way as the single-record endpoints.
Pagination and data freshness
This section covers list pagination behavior and expected data visibility timing after writes.
- List endpoints support
limitandoffset. limitdefaults to100and is clamped to1through250.offsetdefaults to0, and negative values are floored to0.- Single-record writes are immediately visible to reads and Liquid personalization. Bulk writes are applied when Braze processes the queued batch.
- Segment membership based on data objects can lag by up to one hour because calculated filters refresh hourly.
Error behavior
This section summarizes status and error response patterns used across the Data Objects endpoints.
404,409,422, and429return anerrorsarray withidandmessage.400,401, and403return a singleerrorstring.- The bulk endpoints return
400and500errors as anerrorsarray withidandmessage. A400error also includes theparameterat fault when there is one and, for record-level errors, the record’sindex. 422means the request would exceed a product limit. Default limit values vary by company contract.