Skip to content

Data Objects Endpoints

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

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

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 a data-object-schema-mismatch processing failure for the record, such as attributes: 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 of external_id, braze_id, alias, email, or phone.
  • 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_kind values with:
    • GET /data_objects/types/{type_name}/user_relationship_types
    • GET /data_objects/types/{type_name}/object_relationship_types
  • rel_kind is not globally unique across all object type pairs. For example, rel_kind can be subaccount for one pair of object types and partner_account for another.
  • Object relationship writes therefore require both rel_kind and related_type_name to identify the intended relationship type along with the other type of object in the association.
  • If the related_type_name does not match the relationship type for that rel_kind, the request returns 400.

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 attributes field.
  • Object attributes stay nested under to_data_object or from_data_object.
  • PUT replaces relationship attributes, and PATCH merges relationship attributes.

Worked example

This example shows a common account workflow:

  1. Create account/acct-123.
  2. Create account/acct-456 as a child account.
  3. Link a user to acct-123 with rel_kind: account_user.
  4. Link acct-123 to acct-456 with rel_kind: subaccount.

To read back the links:

  • GET /data_objects/objects/account/acct-123/user_relationships for linked users
  • GET /data_objects/objects/account/acct-123/object_relationships for outgoing object links
  • GET /data_objects/objects/account/acct-456/object_relationships?anchor=target for incoming object links

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 202 response 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 returns 202 can 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_name must 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 limit and offset.
  • limit defaults to 100 and is clamped to 1 through 250.
  • offset defaults to 0, and negative values are floored to 0.
  • 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, and 429 return an errors array with id and message.
  • 400, 401, and 403 return a single error string.
  • The bulk endpoints return 400 and 500 errors as an errors array with id and message. A 400 error also includes the parameter at fault when there is one and, for record-level errors, the record’s index.
  • 422 means the request would exceed a product limit. Default limit values vary by company contract.

New Stuff!