Custom Objects Management

Create or update object records in bulk

This endpoint allows you to insert or update multiple records of a custom object in a single API call. The API sends a request to the URL https://api.brevo.com/v3/objects/{object_type}/batch/upsert using the POST method.

This operation is asynchronous. The endpoint returns a processId that can be used to monitor the status of the request. You can refer to the API endpoint here.

Requirements

• Custom objects are only available for Enterprise or Pro plan accounts.
• This endpoint only supports custom objects, it will not create or update any records for Brevo system objects such as contact, company, deal, task, note, store, order, ticket etc.
• The target object type must already exist in your Brevo schema (see create custom objects help article). The endpoint does not create new object types, and will return an invalid object_type error otherwise.
• The attributes in your payload must be previously defined in the schema-attributes and the ones that are not defined are ignored as shown here.
• To associate two object records:
  • An association between the corresponding object types must exist (see here).
  • Both object records must exist before associating them, otherwise the API will return an error.

Limits and behaviour

Associations

• Associations must reference existing object records, otherwise the API returns an error.
• For associating custom objects, either use ext_id or id.
• Custom objects can be associated with Brevo system objects. For example, with object_type as vehicle and associated object_type as company:
  • For associating contacts, contact_id must be used as id in identifiers.
  • For associating companies or deals, use the ext_id in identifiers, and fill it with the Brevo generated company or deal id e.g. company_id as ext_id.

For storing attributes of an object record (while creating or updating an object record)

• Use the attribute_id, which gets generated while creating an object attribute, as a key.
• The attribute_id not defined in the object schema will be simply ignored, they will not be created or throw errors.

CURL request

curl --request POST \
     --url https://api.brevo.com/v3/objects/object_type/batch/upsert \
     --header 'accept: application/json' \
     --header 'api-key: YOUR_API_KEY' \
     --header 'content-type: application/json' \
     --data '
{
  "records": [
    {
      "attributes": {
        "make": "Honda",
        "model": "Civic",
        "color": "Gray",
        "year": 2021,
        "engine_type": "Diesel"
      },
      "identifiers": {
        "id": 400
      },
      "associations": [
        {
          "object_type": "garage",
          "records": [
            {
              "identifiers": {
                "id": 435435
              }
            }
          ]
        },
        {
          "object_type": "insurance",
          "records": [
            {
              "identifiers": {
                "id": 1236
              }
            },
            {
              "identifiers": {
                "ext_id": "f7e8d9c0ba"
              }
            }
          ]
        }
      ]
    }
  ]
}
'

Response

The response codes and their description is mentioned.

A successful response returns a processId and a message.

{
  "processId": 21,
  "message": "Batch object records are being processed"
}

Get the list of object records and total records count for an object

This endpoint allows you to retrieve a paginated list of records of a specific object type, including associated data and a total count of records.

The API sends a request to the URL https://api.brevo.com/v3/objects/{object_type}/recordsusing the GET method. The endpoint returns a list of records and total count of the object records. You can refer to the API endpoint here.

Requirements

• This endpoint currently only supports custom objects, it will not return any records for Brevo system objects like contact, company, deal, task, note, store, order, ticket etc.
• Custom objects are only available for Enterprise or Pro plan accounts.
• Confirm that the object type is already defined in your schema, otherwise this endpoint will not return records for undefined object types.

CURL request

curl --request GET \
     --url 'https://api.brevo.com/v3/objects/object_type/records?sort=desc' \
     --header 'accept: application/json' \
     --header 'api-key: YOUR_API_KEY'

Response

The response codes and their description is mentioned.

The response returns a list of object records with attributes, identifiers and associations. It also returns a total count of records for that object type which is useful for pagination.

{
  "count": 350,
  "records": [
    {
      "createdAt": "2025-07-22T10:20:30Z",
      "updatedAt": "2025-07-22T10:20:30Z",
      "identifiers": {
        "id": 16789,
        "ext_id": "507f1f77bc"
      },
      "attributes": {
        "make": "Toyoto",
        "model": "Corolla",
        "color": "Black",
        "year": 2020,
        "engine_type": "Hybrid"
      },
      "associations": [
        {
          "object_type": "garage",
          "records": [
            {
              "identifiers": {
                "id": 12345
              }
            },
            {
              "identifiers": {
                "id": 45678
              }
            }
          ]
        },
        {
          "object_type": "insurance",
          "records": [
            {
              "identifiers": {
                "id": 98765
              }
            },
            {
              "identifiers": {
                "id": 87654
              }
            }
          ]
        }
      ]
    }
  ]
}