> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developers.brevo.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.brevo.com/_mcp/server. ## 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](/reference/custom-objects/upsertrecords). ### 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](https://help.brevo.com/hc/en-us/articles/25588365458066-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](https://help.brevo.com/hc/en-us/articles/25588365458066-Create-custom-objects#h_01JW89SP9TY0J6J24PRYDMEJD2). * To associate two object records: * An association between the corresponding object types must exist (see [here](https://help.brevo.com/hc/en-us/articles/25588365458066-Create-custom-objects#h_01JW89SP9TFSG04S5NBSCPD7GK)). * Both object records must exist before associating them, otherwise the API returns an error. ### Limits and behaviour | Limit | Value | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | Records per request | 1000 in the array | | Payload size | Total request body must not exceed 1 MB | | Attributes per record | Max 500 attributes per record. Only 500 attributes can be defined for an object type in the database. | | Associations per record | Max 10 associations per associated object type per record. To define more than 10 associations for a given associated object type, run multiple requests. | \ **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. | Attribute name | Datatype | Description | | :------------------------- | :--------------- | :---------------------------------------------------------------------------------- | | `records` | Array | Records to be created | | `attributes` | Object | The properties to set and update | | `associations` | Array | Linked object records | | `associations.object_type` | String | Type of the associated object | | `associations.records` | Array of objects | Records associated with the object type | | `identifiers` | Object | Used for identification of records | | `identifiers.ext_id` | String | ID of record in the external system that client want to store in the object system. | | `identifiers.id` | String | ID of object record generated by Brevo | ### CURL request ```curl 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: | Response code | Description | | :------------ | :----------------------------------------------------------------------------------------------------------------------------------- | | `202` | Batch request accepted for processing of upsert object records | | `400` | Bad request. Error messages may include: invalid `organizationId`, invalid `object_type`, records cannot be empty or more than 1000) | | `403` | Custom objects are not available on this account | | `404` | Object not found for the provided organization or object type | | `500` | Internal server error | A successful response returns a `processId` and a message. ```json { "processId": 21, "message": "Batch object records are being processed" } ``` \ ## 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](/reference/custom-objects/getrecords). ### 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. | Attribute name | Datatype | Description | | :------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------- | | `object_type` | String | Object type for attribute | | `limit` | Integer | Number of records returned per page | | `page_num` | Integer | Page number for pagination. It is used to fetch the object records on a provided page number. Must be a valid positive integer | | `sort` | String | Order of the sort. Accepts two possible values: `asc` or `desc` | | `association` | String | Specifies whether association should be included. Accepts two possible values: `true` or `false`. | ### CURL request ```curl 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: | Response code | Description | | :------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------- | | `200` | A list of object records for an object type. If the association param is set to true, returns 5 associated records per association for an object type. | | `400` | Bad request (e.g., invalid `object_type`, invalid `page_num` provided) | | `403` | Custom objects are not available on this account | | `424` | Primary attribute not found | | `500` | Internal server error | 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). ```json { "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 } } ] } ] } ] } ``` \ ## 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](/reference/custom-objects/get-associated-records). ### 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`. | Attribute name | Datatype | Description | | :------------- | :-------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `object_type` | String | Object type of the source record, exactly as defined in your account. Accepts any object type defined in the account, for example a custom object type or `contact` | | `id` | Integer | Internal Brevo ID of the source record. Must be a positive integer | | `ext_id` | String | External ID of the source record in your system | | `email` | String | Email address of the source contact. Only accepted when `object_type` is `contact` | | `sms` | String | Phone number of the source contact, including the country code, with or without a leading `+`. Only accepted when `object_type` is `contact` | | `type` | Array of string | Restricts the response to the given associated object types. Repeat the parameter to request several types. Maximum 5 per call | | `offset` | Integer | Number of records to skip before the first record of the page. Defaults to 0 | ### 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 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 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: | Response code | Description | | :------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `200` | A page of records associated with the source record | | `400` | Bad request (e.g., none or several of `id`, `ext_id`, `email` and `sms` provided, `email` or `sms` used with an `object_type` other than `contact`, more than 5 values passed to `type`, or an object type that is not defined in the account) | | `404` | No record matches the provided identifier for this object type | | `500` | Internal server error | 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. ```json { "items": [ { "type": "garage", "object": { "id": 12345, "ext_id": "f7e8d9c0ba", "attributes": { "name": "Downtown Motors", "city": "Paris" }, "created_at": "2026-07-22T10:20:30Z", "updated_at": "2026-07-22T10:20:30Z" } }, { "type": "contact", "object": { "id": 402, "attributes": { "email": "jane.doe@example.com", "first_name": "Jane", "last_name": "Doe", "ext_id": "crm-4471" } } } ], "offset": 0, "has_more": true } ```