{"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.\nThis feature is in beta. These are subject to change.</Note>\nPerforms 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.\n\n**How Upsert Works:**\n- **Create**: Omit `identifiers`, or provide only `ext_id` (if it doesn't already exist). A new record is created with a Brevo-generated `id`.\n- **Update**: Provide `id` (Brevo internal ID) or an `ext_id` that already exists. The matching record is updated with the new attribute values.\n- **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.\n\n**Request Structure:**\nEach object record in the `records` array can include:\n- `identifiers`: Either `id` (internal Brevo ID) or `ext_id` (your external system ID) — required for updates. **Note:** use `id` (singular), not `ids`.\n- `attributes`: Key-value pairs where each key is the attribute **key** (e.g., `company_name`), not the attribute label (e.g., \"Company Name\").\n- `associations`: Controls linking and unlinking of associated records (optional). Each entry specifies:\n    - `object_type`: The type of the associated object\n    - `action`: `link` (default) to create the association, or `unlink` to remove it\n    - `records`: The associated records to link or unlink (each identified by `ext_id` or `id`)\n    - **Unlink is idempotent** — unlinking a non-existing association is a no-op (no error returned)\n    - `link` and `unlink` actions can be submitted for the same `object_type` in a single record entry\n    - Both associated records must already exist before a link can be created\n\n> **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.\n\n**Asynchronous Processing:**\n- Returns immediately with a `processId` (HTTP 202 Accepted)\n- Use the processId to track status via the Get process API\n\n**API and Schema Limitations:**\n- Max 1000 object records per request\n- Max request body size: 1 MB\n- Max 500 attributes per object record (matches the schema limit of 500 attributes per object)\n- Unknown attribute keys are silently ignored (no error, no attribute creation)\n- Max 10 association records per associated object-type in each record of the request. If you need more, send multiple requests.\n\n**Important Behaviors:**\n- The object schema must be created before upserting records\n- Unknown attribute keys are silently ignored (no error, no creation)\n- Both associated object records must already exist before creating a link association\n- Unlink operations are idempotent: attempting to unlink a non-existing association returns success\n- `link` and `unlink` actions can be submitted for the same `object_type` in a single record entry\n- Contact objects cannot be created via this endpoint\n- For `category` and `multiple_category` attributes, pass the option **key** as the value (not the option label or option ID).\n- 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`.\n\n**Errors:**\n- Make sure both object records exist before associating them, else the API will return an error.\n- 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.\nThis feature is in beta. These are subject to change.</Note>\nThis 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.\nThe request is accepted and processed asynchronously. You can track the status of the deletion process using the returned **processId**.\n**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\n","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.\nFor `category` or `multiple_category` attributes, the value is the option **key** (not the option label or option ID).\n","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`.\n- `ext_id`: Your external system's identifier for this record.\n- `id`: Internal Brevo record ID.\n","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.\nFor `category` or `multiple_category` attributes, the value is the option **key** (not the option label or option ID).\n"},"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`.\n- `ext_id`: Your external system's identifier for this record.\n- `id`: Internal Brevo record ID.\n"},"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."}}}}