Generic create, read and delete over account-defined custom object record types, letting an account model data Brevo does not ship natively — subscription dates, store locations, bookings — and use it in customer journeys.
openapi: 3.1.0
info:
title: Object Management
version: 1.0.0
paths:
/objects/{object_type}/batch/upsert:
post:
operationId: upsertrecords
summary: Create/Update object records in bulk
description: >-
<Note title="Enterprise access only">Custom objects are only available to Enterprise plans.
This feature is in beta. These are subject to change.</Note>
Performs bulk create or update (upsert) operations for object records in a single asynchronous request. This
endpoint is optimized for high-volume data imports and synchronization scenarios.
**How Upsert Works:**
- **Create**: Omit `identifiers`, or provide only `ext_id` (if it doesn't already exist). A new record is
created with a Brevo-generated `id`.
- **Update**: Provide `id` (Brevo internal ID) or an `ext_id` that already exists. The matching record is
updated with the new attribute values.
- **Important:** `id` is for **updates only**. Providing an `id` that does not belong to an existing record will
fail during async processing (the HTTP response will still be 202, but the record will be rejected in the
background). To create a new record with a stable external reference, use `ext_id` instead.
**Request Structure:**
Each object record in the `records` array can include:
- `identifiers`: Either `id` (internal Brevo ID) or `ext_id` (your external system ID) — required for updates.
**Note:** use `id` (singular), not `ids`.
- `attributes`: Key-value pairs where each key is the attribute **key** (e.g., `company_name`), not the
attribute label (e.g., "Company Name").
- `associations`: Controls linking and unlinking of associated records (optional). Each entry specifies:
- `object_type`: The type of the associated object
- `action`: `link` (default) to create the association, or `unlink` to remove it
- `records`: The associated records to link or unlink (each identified by `ext_id` or `id`)
- **Unlink is idempotent** — unlinking a non-existing association is a no-op (no error returned)
- `link` and `unlink` actions can be submitted for the same `object_type` in a single record entry
- Both associated records must already exist before a link can be created
> **Common mistake:** Passing the attribute **label** (the display name you see in the UI) instead of the
attribute **key** will cause the attribute to be silently ignored and the record may not be created as expected.
**Asynchronous Processing:**
- Returns immediately with a `processId` (HTTP 202 Accepted)
- Use the processId to track status via the Get process API
**API and Schema Limitations:**
- Max 1000 object records per request
- Max request body size: 1 MB
- Max 500 attributes per object record (matches the schema limit of 500 attributes per object)
- Unknown attribute keys are silently ignored (no error, no attribute creation)
- Max 10 association records per associated object-type in each record of the request. If you need more, send
multiple requests.
**Important Behaviors:**
- The object schema must be created before upserting records
- Unknown attribute keys are silently ignored (no error, no creation)
- Both associated object records must already exist before creating a link association
- Unlink operations are idempotent: attempting to unlink a non-existing association returns success
- `link` and `unlink` actions can be submitted for the same `object_type` in a single record entry
- Contact objects cannot be created via this endpoint
- For `category` and `multiple_category` attributes, pass the option **key** as the value (not the option label
or option ID).
- The `id` identifier (internal Brevo ID) can only be used for **updating** existing records. To create new
records, either omit identifiers (Brevo auto-generates an ID) or provide an `ext_id`.
**Errors:**
- Make sure both object records exist before associating them, else the API will return an error.
- This route does not create objects. The object where the object records are upserted by this API must be
created already else the API will return an error "invalid object type".
tags:
- customObjects
parameters:
- name: object_type
in: path
description: >-
Object type for the records to upsert. Must be a previously created custom object type. Only lowercase
alphanumeric characters and underscores are allowed (max 32 characters).
required: true
schema:
type: string
- name: api-key
in: header
description: The API key should be passed in the request headers as `api-key` for authentication.
required: true
schema:
type: string
responses:
'202':
description: Batch request accepted for processing of upsert object records.
content:
application/json:
schema:
$ref: '#/components/schemas/Custom Objects_upsertrecords_Response_202'
'400':
description: Bad request (e.g., invalid organization ID, invalid object_type, records cannot be empty or more than 1000)
content:
application/json:
schema:
description: Any type
'403':
description: >-
Custom objects are not available on this account, or upsert of Brevo standard object records is not
supported via this endpoint.
content:
application/json:
schema:
description: Any type
'404':
description: Object not found for the provided organization or object type
content:
application/json:
schema:
description: Any type
'500':
description: Internal server error
content:
application/json:
schema:
description: Any type
requestBody:
description: Payload for batch upsert object records with associations
content:
application/json:
schema:
type: object
properties:
records:
type: array
items:
$ref: >-
#/components/schemas/ObjectsObjectTypeBatchUpsertPostRequestBodyContentApplicationJsonSchemaRecordsItems
description: List of object records to be upsert. Each record can have attributes, identifiers, and associations.
required:
- records
/objects/{object_type}/records:
get:
operationId: getrecords
summary: Get the list of object records and total records count for an object.
description: >-
<Note title="Enterprise access only">Custom objects are only available to Enterprise plans.
This feature is in beta. These are subject to change.</Note>
This API retrieves a list of object records along with their associated records and provides the total count of
records for the specified object. **Note**: Contact as object type is not supported in this endpoint.
tags:
- customObjects
parameters:
- name: object_type
in: path
description: >-
Object type for the records to retrieve. Must be a previously created custom object type. Contact as object
type is not supported in this endpoint.
required: true
schema:
type: string
- name: limit
in: query
description: Number of records returned per page
required: true
schema:
type: integer
format: int64
- name: page_num
in: query
description: >-
Page number for pagination. It's used to fetch the object records on a provided page number. Must be a valid
positive integer.
required: true
schema:
type: integer
format: int64
- name: sort
in: query
description: Sort order, must be 'asc' or 'desc'. Default to 'desc' if not provided.
required: false
schema:
$ref: '#/components/schemas/ObjectsObjectTypeRecordsGetParametersSort'
default: desc
- name: association
in: query
description: Whether to include associations, must be 'true' or 'false'. Default to 'false' if not provided.
required: false
schema:
$ref: '#/components/schemas/ObjectsObjectTypeRecordsGetParametersAssociation'
- name: api-key
in: header
description: The API key should be passed in the request headers as `api-key` for authentication.
required: true
schema:
type: string
responses:
'200':
description: >-
A list of object records for an object type. If association param is set true it will return 5 associated
records per association for an object type.
content:
application/json:
schema:
$ref: '#/components/schemas/Custom Objects_getrecords_Response_200'
'400':
description: Bad request (e.g., invalid object_type, invalid page number provided)
content:
application/json:
schema:
description: Any type
'403':
description: Custom objects are not available on this account.
content:
application/json:
schema:
description: Any type
'424':
description: primary attribute not found
content:
application/json:
schema:
description: Any type
'500':
description: Internal server error
content:
application/json:
schema:
description: Any type
/objects/{object_type}/batch/delete:
post:
operationId: batchDeleteObjectRecords
summary: Delete multiple object records (up to 1000) asynchronously
description: >
Use this endpoint to delete multiple object records of the same object-type in one request.
The request is accepted and processed asynchronously. You can track the status of the deletion process using the
returned **processId**.
**Limitations:** - Each request can contain up to **1000** object record identifiers - Either `ids` or `ext_ids`
must be provided, but **not both** in the same request - Deletion of Brevo standard object records is not
supported via this endpoint - If more records must be deleted, send multiple batch requests
tags:
- customObjects
parameters:
- name: object_type
in: path
description: Object type for the records to delete
required: true
schema:
type: string
- name: api-key
in: header
description: The API key should be passed in the request headers as `api-key` for authentication.
required: true
schema:
type: string
responses:
'202':
description: Batch request accepted for deletion - process started
content:
application/json:
schema:
$ref: '#/components/schemas/Custom Objects_batchDeleteObjectRecords_Response_202'
'400':
description: >-
Invalid request (e.g., invalid object_type, invalid request body, both ids and ext_ids provided, or exceeds
1000 identifiers limit)
content:
application/json:
schema:
description: Any type
'403':
description: Deletion of Brevo standard object records is not supported via this endpoint
content:
application/json:
schema:
description: Any type
'500':
description: Internal server error
content:
application/json:
schema:
description: Any type
requestBody:
description: List of object record identifiers to delete
content:
application/json:
schema:
type: object
properties:
identifiers:
$ref: >-
#/components/schemas/ObjectsObjectTypeBatchDeletePostRequestBodyContentApplicationJsonSchemaIdentifiers
description: Either `ids` or `ext_ids` must be provided, but not both in the same request.
servers:
- url: https://api.brevo.com/v3
description: https://api.brevo.com/v3
components:
schemas:
ObjectsObjectTypeBatchUpsertPostRequestBodyContentApplicationJsonSchemaRecordsItems:
oneOf:
- description: Reference to ObjectsObjectTypeBatchUpsertPostRequestBodyContentApplicationJsonSchemaRecordsItems0
title: ObjectsObjectTypeBatchUpsertPostRequestBodyContentApplicationJsonSchemaRecordsItems
Custom Objects_upsertrecords_Response_202:
type: object
properties:
message:
type: string
processId:
type: integer
format: int64
description: >-
Unique Id for the batch process used to track the status of the batch. **How to use this processId:**
Refer to the [Get process status API](https://developers.brevo.com/reference/get-process) to check the
execution status of this batch using the returned `processId`.
title: Custom Objects_upsertrecords_Response_202
ObjectsObjectTypeRecordsGetParametersSort:
type: string
enum:
- asc
- desc
default: desc
title: ObjectsObjectTypeRecordsGetParametersSort
ObjectsObjectTypeRecordsGetParametersAssociation:
type: string
enum:
- 'true'
- 'false'
title: ObjectsObjectTypeRecordsGetParametersAssociation
ObjectsObjectTypeRecordsGetResponsesContentApplicationJsonSchemaRecordsItemsAssociationsItemsOneOf0RecordsItemsOneOf0Identifiers:
type: object
properties:
id:
type: integer
description: Internal ID of the object record generated by Brevo
description: Identifiers attached with the associated object record.
title: >-
ObjectsObjectTypeRecordsGetResponsesContentApplicationJsonSchemaRecordsItemsAssociationsItemsOneOf0RecordsItemsOneOf0Identifiers
ObjectsObjectTypeRecordsGetResponsesContentApplicationJsonSchemaRecordsItemsAssociationsItemsOneOf0RecordsItems0:
type: object
properties:
identifiers:
$ref: >-
#/components/schemas/ObjectsObjectTypeRecordsGetResponsesContentApplicationJsonSchemaRecordsItemsAssociationsItemsOneOf0RecordsItemsOneOf0Identifiers
description: Identifiers attached with the associated object record.
title: ObjectsObjectTypeRecordsGetResponsesContentApplicationJsonSchemaRecordsItemsAssociationsItemsOneOf0RecordsItems0
ObjectsObjectTypeRecordsGetResponsesContentApplicationJsonSchemaRecordsItemsAssociationsItemsOneOf0RecordsItemsOneOf1Identifiers:
type: object
properties:
id:
type: integer
description: Internal ID of the object record generated by Brevo
description: Identifiers attached with the associated object record.
title: >-
ObjectsObjectTypeRecordsGetResponsesContentApplicationJsonSchemaRecordsItemsAssociationsItemsOneOf0RecordsItemsOneOf1Identifiers
ObjectsObjectTypeRecordsGetResponsesContentApplicationJsonSchemaRecordsItemsAssociationsItemsOneOf0RecordsItems1:
type: object
properties:
identifiers:
$ref: >-
#/components/schemas/ObjectsObjectTypeRecordsGetResponsesContentApplicationJsonSchemaRecordsItemsAssociationsItemsOneOf0RecordsItemsOneOf1Identifiers
description: Identifiers attached with the associated object record.
title: ObjectsObjectTypeRecordsGetResponsesContentApplicationJsonSchemaRecordsItemsAssociationsItemsOneOf0RecordsItems1
ObjectsObjectTypeRecordsGetResponsesContentApplicationJsonSchemaRecordsItemsAssociationsItemsOneOf0RecordsItems:
oneOf:
- $ref: >-
#/components/schemas/ObjectsObjectTypeRecordsGetResponsesContentApplicationJsonSchemaRecordsItemsAssociationsItemsOneOf0RecordsItems0
- $ref: >-
#/components/schemas/ObjectsObjectTypeRecordsGetResponsesContentApplicationJsonSchemaRecordsItemsAssociationsItemsOneOf0RecordsItems1
title: ObjectsObjectTypeRecordsGetResponsesContentApplicationJsonSchemaRecordsItemsAssociationsItemsOneOf0RecordsItems
ObjectsObjectTypeRecordsGetResponsesContentApplicationJsonSchemaRecordsItemsAssociationsItems0:
type: object
properties:
object_type:
type: string
description: Type of the associated object
records:
type: array
items:
$ref: >-
#/components/schemas/ObjectsObjectTypeRecordsGetResponsesContentApplicationJsonSchemaRecordsItemsAssociationsItemsOneOf0RecordsItems
title: ObjectsObjectTypeRecordsGetResponsesContentApplicationJsonSchemaRecordsItemsAssociationsItems0
ObjectsObjectTypeRecordsGetResponsesContentApplicationJsonSchemaRecordsItemsAssociationsItemsOneOf1RecordsItemsOneOf0Identifiers:
type: object
properties:
id:
type: integer
description: Internal ID of the insurance object record generated by Brevo
description: Identifiers attached with the associated object record. Only includes the internal ID.
title: >-
ObjectsObjectTypeRecordsGetResponsesContentApplicationJsonSchemaRecordsItemsAssociationsItemsOneOf1RecordsItemsOneOf0Identifiers
ObjectsObjectTypeRecordsGetResponsesContentApplicationJsonSchemaRecordsItemsAssociationsItemsOneOf1RecordsItems0:
type: object
properties:
identifiers:
$ref: >-
#/components/schemas/ObjectsObjectTypeRecordsGetResponsesContentApplicationJsonSchemaRecordsItemsAssociationsItemsOneOf1RecordsItemsOneOf0Identifiers
description: Identifiers attached with the associated object record. Only includes the internal ID.
title: ObjectsObjectTypeRecordsGetResponsesContentApplicationJsonSchemaRecordsItemsAssociationsItemsOneOf1RecordsItems0
ObjectsObjectTypeRecordsGetResponsesContentApplicationJsonSchemaRecordsItemsAssociationsItemsOneOf1RecordsItemsOneOf1Identifiers:
type: object
properties:
id:
type: integer
description: Internal ID of the insurance object record generated by Brevo
description: Identifiers attached with the associated object record. Only includes the internal ID.
title: >-
ObjectsObjectTypeRecordsGetResponsesContentApplicationJsonSchemaRecordsItemsAssociationsItemsOneOf1RecordsItemsOneOf1Identifiers
ObjectsObjectTypeRecordsGetResponsesContentApplicationJsonSchemaRecordsItemsAssociationsItemsOneOf1RecordsItems1:
type: object
properties:
identifiers:
$ref: >-
#/components/schemas/ObjectsObjectTypeRecordsGetResponsesContentApplicationJsonSchemaRecordsItemsAssociationsItemsOneOf1RecordsItemsOneOf1Identifiers
description: Identifiers attached with the associated object record. Only includes the internal ID.
title: ObjectsObjectTypeRecordsGetResponsesContentApplicationJsonSchemaRecordsItemsAssociationsItemsOneOf1RecordsItems1
ObjectsObjectTypeRecordsGetResponsesContentApplicationJsonSchemaRecordsItemsAssociationsItemsOneOf1RecordsItems:
oneOf:
- $ref: >-
#/components/schemas/ObjectsObjectTypeRecordsGetResponsesContentApplicationJsonSchemaRecordsItemsAssociationsItemsOneOf1RecordsItems0
- $ref: >-
#/components/schemas/ObjectsObjectTypeRecordsGetResponsesContentApplicationJsonSchemaRecordsItemsAssociationsItemsOneOf1RecordsItems1
title: ObjectsObjectTypeRecordsGetResponsesContentApplicationJsonSchemaRecordsItemsAssociationsItemsOneOf1RecordsItems
ObjectsObjectTypeRecordsGetResponsesContentApplicationJsonSchemaRecordsItemsAssociationsItems1:
type: object
properties:
object_type:
type: string
description: Type of the associated object
records:
type: array
items:
$ref: >-
#/components/schemas/ObjectsObjectTypeRecordsGetResponsesContentApplicationJsonSchemaRecordsItemsAssociationsItemsOneOf1RecordsItems
title: ObjectsObjectTypeRecordsGetResponsesContentApplicationJsonSchemaRecordsItemsAssociationsItems1
ObjectsObjectTypeRecordsGetResponsesContentApplicationJsonSchemaRecordsItemsAssociationsItems:
oneOf:
- $ref: >-
#/components/schemas/ObjectsObjectTypeRecordsGetResponsesContentApplicationJsonSchemaRecordsItemsAssociationsItems0
- $ref: >-
#/components/schemas/ObjectsObjectTypeRecordsGetResponsesContentApplicationJsonSchemaRecordsItemsAssociationsItems1
title: ObjectsObjectTypeRecordsGetResponsesContentApplicationJsonSchemaRecordsItemsAssociationsItems
ObjectsObjectTypeRecordsGetResponsesContentApplicationJsonSchemaRecordsItemsAttributes:
type: object
properties: {}
description: >
Key-value pairs of attribute data for the object record. Each key is the attribute **key** (e.g.,
`company_name`, `engine_type`), not the attribute label (e.g., "Company Name", "Engine Type"). Only attributes
that already exist in the object schema will be present.
For `category` or `multiple_category` attributes, the value is the option **key** (not the option label or
option ID).
title: ObjectsObjectTypeRecordsGetResponsesContentApplicationJsonSchemaRecordsItemsAttributes
ObjectsObjectTypeRecordsGetResponsesContentApplicationJsonSchemaRecordsItemsIdentifiers:
type: object
properties:
ext_id:
type: string
description: External ID of the record in your system.
id:
type: integer
description: Internal ID of the object record generated by Brevo.
description: |
Identifiers for the object record. Supports `id` (singular, not `ids`) or `ext_id`.
- `ext_id`: Your external system's identifier for this record.
- `id`: Internal Brevo record ID.
title: ObjectsObjectTypeRecordsGetResponsesContentApplicationJsonSchemaRecordsItemsIdentifiers
ObjectsObjectTypeRecordsGetResponsesContentApplicationJsonSchemaRecordsItems:
type: object
properties:
associations:
type: array
items:
$ref: >-
#/components/schemas/ObjectsObjectTypeRecordsGetResponsesContentApplicationJsonSchemaRecordsItemsAssociationsItems
description: >-
List of associations for the object record. If association query param is true it will return 5 associated
records per association.
attributes:
$ref: '#/components/schemas/ObjectsObjectTypeRecordsGetResponsesContentApplicationJsonSchemaRecordsItemsAttributes'
description: >
Key-value pairs of attribute data for the object record. Each key is the attribute **key** (e.g.,
`company_name`, `engine_type`), not the attribute label (e.g., "Company Name", "Engine Type"). Only
attributes that already exist in the object schema will be present.
For `category` or `multiple_category` attributes, the value is the option **key** (not the option label or
option ID).
createdAt:
type: string
format: date-time
description: Timestamp when the object record was created
identifiers:
$ref: '#/components/schemas/ObjectsObjectTypeRecordsGetResponsesContentApplicationJsonSchemaRecordsItemsIdentifiers'
description: |
Identifiers for the object record. Supports `id` (singular, not `ids`) or `ext_id`.
- `ext_id`: Your external system's identifier for this record.
- `id`: Internal Brevo record ID.
updatedAt:
type: string
format: date-time
description: Timestamp when the object record was last updated
title: ObjectsObjectTypeRecordsGetResponsesContentApplicationJsonSchemaRecordsItems
Custom Objects_getrecords_Response_200:
type: object
properties:
count:
type: integer
format: int64
description: Total number of object records for an object type.
records:
type: array
items:
$ref: '#/components/schemas/ObjectsObjectTypeRecordsGetResponsesContentApplicationJsonSchemaRecordsItems'
title: Custom Objects_getrecords_Response_200
ObjectsObjectTypeBatchDeletePostRequestBodyContentApplicationJsonSchemaIdentifiers:
oneOf:
- description: Reference to ObjectsObjectTypeBatchDeletePostRequestBodyContentApplicationJsonSchemaIdentifiers0
- description: Reference to ObjectsObjectTypeBatchDeletePostRequestBodyContentApplicationJsonSchemaIdentifiers1
description: Either `ids` or `ext_ids` must be provided, but not both in the same request.
title: ObjectsObjectTypeBatchDeletePostRequestBodyContentApplicationJsonSchemaIdentifiers
Custom Objects_batchDeleteObjectRecords_Response_202:
type: object
properties:
processId:
type: integer
format: int64
description: Identifier for batch process tracking
message:
type: string
title: Custom Objects_batchDeleteObjectRecords_Response_202
securitySchemes:
api-key:
type: apiKey
in: header
name: api-key
description: The API key should be passed in the request headers as `api-key` for authentication.