Replace custom object

Use this endpoint to create or replace a custom object with full-attribute replacement semantics.

important

Custom Objects is currently in early access. Your workspace must be enabled before the Custom Objects API key permissions appear on Settings > API Keys.

Prerequisites

To use this endpoint, you need an API key with custom_objects.update.

Rate limit

This endpoint is in the Custom Objects write bucket with a default limit of 50 requests per minute.

Path parameters

The following table lists and describes the path parameters for the /custom_objects/objects/{type_name}/{external_id} endpoint.

Request parameters

The following table lists and describes the JSON request body parameters for the /custom_objects/objects/{type_name}/{external_id} endpoint.

Example request

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

Sample request payload

1
2
3
4
5
{
  "attributes": {
    "name": "Updated Account"
  }
}

Sample cURL request

This example replaces the stored attributes on acct-123 with the ones in the payload. If no record with that identifier exists, this request creates it.

1
2
3
4
5
6
7
8
curl --location --request PUT 'https://rest.iad-01.braze.com/custom_objects/objects/account/acct-123' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "attributes": {
    "name": "Updated Account"
  }
}'

Response

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

Example success response

The status code 200 could return the following response body. This endpoint returns 200 whether the request created or replaced the object.

1
2
3
4
5
6
7
{
  "custom_object": {
    "type_name": "account",
    "external_id": "acct-123",
    "attributes": { "name": "Updated Account" }
  }
}

Response parameters

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

Errors

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