Create or replace object relationships in bulk

Use this endpoint to create or replace up to 50 object-to-object relationships in one request.

important

Data Objects is generally available, but your workspace must be provisioned for Accounts before you can use this endpoint. To request provisioning, go to Data Settings > Accounts and complete the questionnaire. For details, see Enable Accounts.

Braze accepts the request and processes it in the background. A 202 response means the batch is queued, not applied. To change one relationship and see the change right away, use Replace object relationship. For when to use each, see Bulk endpoints.

Prerequisites

To use this endpoint, you need an API key with data_objects.object_relationships.bulk_upsert. The single-record permissions, such as data_objects.object_relationships.create, don’t grant access to this endpoint.

Rate limit

This endpoint is in the Data Objects bulk write bucket with a default limit of 1,000 requests per minute per workspace. The limit is shared across all six bulk endpoints and with Cloud Data Ingestion syncs of data objects, and is separate from the single-record write limit.

Request parameters

The following table lists and describes the JSON request body parameters for the /data_objects/object_relationships endpoint.

How Braze processes the batch

• Validation is all-or-nothing. If any record fails validation, Braze rejects the whole request with 400, stores nothing, and lists every error. Fix the errors and resend the whole request.
• Lookups happen during processing. Braze checks whether the types, relationship type, and objects exist, and whether the attributes match the relationship type’s fields, when it processes the batch. A request that returns 202 can still produce failures for individual records later. See Processing failures.
• Records are ordered by receipt time. Braze stamps every record with the time it received the request, so don’t send updated_at. Braze rejects a request that includes it. When two requests change the same relationship, the one Braze received later wins, and Braze skips an older write that arrives afterward.
• Relationships can wait on their objects. A relationship whose source or target object doesn’t exist yet waits instead of failing right away. Braze retries for about 40 hours (10 attempts). If the object still doesn’t exist after that, the record fails with data-object-dependency-not-found.

Example request

This section includes a sample JSON payload and a sample cURL request.

Sample request payload

1
2
3
4
5
6
7
8
9
10
11
12

{
  "records": [
    {
      "type_name": "contact",
      "object_id": "contact-001",
      "rel_kind": "works_at",
      "related_type_name": "account",
      "related_object_id": "acct-001",
      "attributes": {"since": "2024-01-15T00:00:00Z"}
    }
  ]
}

Sample cURL request

This example links contact-001 to acct-001 with the works_at relationship type and records when the relationship started.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

curl --location --request PUT 'https://rest.iad-01.braze.com/data_objects/object_relationships' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "records": [
    {
      "type_name": "contact",
      "object_id": "contact-001",
      "rel_kind": "works_at",
      "related_type_name": "account",
      "related_object_id": "acct-001",
      "attributes": {"since": "2024-01-15T00:00:00Z"}
    }
  ]
}'

Response

This section includes a sample successful response and the response fields.

Example success response

The status code 202 could return the following response body.

1
2
3
4
5

{
  "source_import_id": "api-20261022T153012123456-9f3a1c2b",
  "status": "queued",
  "record_count": 1
}

Response parameters

The following table lists and describes the fields in a successful response.

Processing failures

Braze doesn’t return these codes from the endpoint. It records them for individual records when it processes a queued batch.

Errors

A 400 response means Braze stored nothing. Each error has an id, a message, the parameter at fault when there is one, and, for record-level errors, the record’s index (its 0-based position in records).

1
2
3
4
5

{
  "errors": [
    {"index": 0, "id": "schema-mismatch", "parameter": "rel_kind", "message": "rel_kind is required"}
  ]
}

The following table lists common errors for this endpoint and how to resolve them.