Custom objects management

Create or update object records in bulk

Insert or update multiple records of a custom object in a single API call. Send a POST request to https://api.brevo.com/v3/objects/{object_type}/batch/upsert.

This operation is asynchronous. The endpoint returns a processId you can use to monitor the request status. See 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 records for Brevo system objects such as contact, company, deal, task, note, store, order, or ticket.
• The target object type must already exist in your Brevo schema (see the create custom objects help article). The endpoint does not create new object types and returns an invalid object_type error otherwise.
• Attributes in your payload must be defined in the schema attributes. Undefined attributes 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 returns an error.

Limits and behaviour

Associations

• Associations must reference existing object records, otherwise the API returns an error.
• To associate custom objects, use either 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:
  • To associate contacts, use contact_id as id in identifiers.
  • To associate companies or deals, use ext_id in identifiers and fill it with the Brevo-generated company or deal ID (e.g. company_id as ext_id).

Storing attributes of an object record (when creating or updating one)

• Use the attribute_id generated when the object attribute was created as the key.
• An attribute_id not defined in the object schema is ignored — it will not be created and does not throw an error.

CURL request

1
curl --request POST \
2
     --url https://api.brevo.com/v3/objects/object_type/batch/upsert \
3
     --header 'accept: application/json' \
4
     --header 'api-key: YOUR_API_KEY' \
5
     --header 'content-type: application/json' \
6
     --data '
7
{
8
  "records": [
9
    {
10
      "attributes": {
11
        "make": "Honda",
12
        "model": "Civic",
13
        "color": "Gray",
14
        "year": 2021,
15
        "engine_type": "Diesel"
16
      },
17
      "identifiers": {
18
        "id": 400
19
      },
20
      "associations": [
21
        {
22
          "object_type": "garage",
23
          "records": [
24
            {
25
              "identifiers": {
26
                "id": 435435
27
              }
28
            }
29
          ]
30
        },
31
        {
32
          "object_type": "insurance",
33
          "records": [
34
            {
35
              "identifiers": {
36
                "id": 1236
37
              }
38
            },
39
            {
40
              "identifiers": {
41
                "ext_id": "f7e8d9c0ba"
42
              }
43
            }
44
          ]
45
        }
46
      ]
47
    }
48
  ]
49
}
50
'

Response

Response codes:

A successful response returns a processId and a message.

1
{
2
  "processId": 21,
3
  "message": "Batch object records are being processed"
4
}

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

Retrieve a paginated list of records for a specific object type, including associated data and a total record count.

Send a GET request to https://api.brevo.com/v3/objects/{object_type}/records. The endpoint returns a list of records and the total count of object records. See the API endpoint here.

Requirements

• This endpoint only supports custom objects. It will not return records for Brevo system objects such as contact, company, deal, task, note, store, order, or ticket.
• Custom objects are only available for Enterprise or Pro plan accounts.
• Confirm the object type is already defined in your schema. The endpoint does not return records for undefined object types.

CURL request

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

Response

Response codes:

The response returns a list of object records with attributes, identifiers, and associations, plus the total count of records for that object type (useful for pagination).

1
{
2
  "count": 350,
3
  "records": [
4
    {
5
      "createdAt": "2025-07-22T10:20:30Z",
6
      "updatedAt": "2025-07-22T10:20:30Z",
7
      "identifiers": {
8
        "id": 16789,
9
        "ext_id": "507f1f77bc"
10
      },
11
      "attributes": {
12
        "make": "Toyoto",
13
        "model": "Corolla",
14
        "color": "Black",
15
        "year": 2020,
16
        "engine_type": "Hybrid"
17
      },
18
      "associations": [
19
        {
20
          "object_type": "garage",
21
          "records": [
22
            {
23
              "identifiers": {
24
                "id": 12345
25
              }
26
            },
27
            {
28
              "identifiers": {
29
                "id": 45678
30
              }
31
            }
32
          ]
33
        },
34
        {
35
          "object_type": "insurance",
36
          "records": [
37
            {
38
              "identifiers": {
39
                "id": 98765
40
              }
41
            },
42
            {
43
              "identifiers": {
44
                "id": 87654
45
              }
46
            }
47
          ]
48
        }
49
      ]
50
    }
51
  ]
52
}