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

$
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

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

$
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

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
}

Get the records associated with an object record

Retrieve the records associated with a single source record. Associations of every type come back together in one paginated list, ordered by association creation time with the most recently created association first.

Send a GET request to https://api.brevo.com/v3/objects/{object_type}/associated-records. See the API endpoint here.

Requirements

• Custom objects are only available for Enterprise or Pro plan accounts.
• Use object types exactly as they are defined in your account, both in the path and in the type filter. An object type that does not exist in your account returns 400.
• Identify the source record with exactly one of id, ext_id, email or sms. Passing none of them, or more than one, returns 400.

Pagination

Results are returned 20 per page. The page size is fixed and cannot be changed. Increase offset by 20 to walk through the pages until has_more is false. An offset beyond the last record returns an empty items array with has_more set to false.

Working with contacts

• contact is supported both as the source object_type and as an associated object type.
• If several contacts share the same ext_id, email or sms, identify the contact by id to be sure of which one is used.
• An sms value may be given with or without a leading +. Percent-encode the + as %2B, because a literal + in a query string is read as a space.
• Contacts returned in items carry all of the contact’s attributes, with attribute keys in lowercase — email, first_name, last_name, sms, ext_id, and any other contact attribute lowercased.
• For contacts, ext_id, created_at and updated_at are not returned on object. A contact’s external ID is available as attributes.ext_id when it is set.

CURL request

$
curl --request GET \
>
     --url 'https://api.brevo.com/v3/objects/contact/associated-records?email=jane.doe@example.com' \
>
     --header 'accept: application/json' \
>
     --header 'api-key: YOUR_API_KEY'

Filter the response to specific associated object types:

$
curl --request GET \
>
     --url 'https://api.brevo.com/v3/objects/vehicle/associated-records?ext_id=507f1f77bc&type=garage' \
>
     --header 'accept: application/json' \
>
     --header 'api-key: YOUR_API_KEY'

Response

Response codes:

The response returns the associated records for the page, the requested offset, and whether more records remain. On each item, ext_id, attributes, created_at and updated_at are omitted when they are not available for the record.

1
{
2
  "items": [
3
    {
4
      "type": "garage",
5
      "object": {
6
        "id": 12345,
7
        "ext_id": "f7e8d9c0ba",
8
        "attributes": {
9
          "name": "Downtown Motors",
10
          "city": "Paris"
11
        },
12
        "created_at": "2026-07-22T10:20:30Z",
13
        "updated_at": "2026-07-22T10:20:30Z"
14
      }
15
    },
16
    {
17
      "type": "contact",
18
      "object": {
19
        "id": 402,
20
        "attributes": {
21
          "email": "jane.doe@example.com",
22
          "first_name": "Jane",
23
          "last_name": "Doe",
24
          "ext_id": "crm-4471"
25
        }
26
      }
27
    }
28
  ],
29
  "offset": 0,
30
  "has_more": true
31
}