Track contact interactions by creating individual or batched events against a contact identifier, feeding automation triggers and segmentation. Batch requests wrap the event array in an events object.
openapi: 3.1.0
info:
title: Events
version: 1.0.0
paths:
/events:
get:
operationId: getEvents
summary: Get events
description: |-
<Note>
This endpoint currently only supports custom events.
</Note>
Retrieve a list of events filtered by various criteria.
tags:
- event
parameters:
- name: contact_id
in: query
description: Filter by contact ID (repeatable)
required: false
schema:
type: array
items:
type: integer
format: int64
- name: event_name
in: query
description: Filter by event name (repeatable)
required: false
schema:
type: array
items:
type: string
- name: object_type
in: query
description: Filter by object type (repeatable)
required: false
schema:
type: array
items:
type: string
- name: startDate
in: query
description: >-
Mandatory if endDate is used. Start of date range (YYYY-MM-DD or RFC3339). Defaults to 6 months ago when
omitted alongside endDate. Must be ≤ endDate.
required: false
schema:
type: string
- name: endDate
in: query
description: Mandatory if startDate is used. End of date range (YYYY-MM-DD or RFC3339). Must be ≥ startDate.
required: false
schema:
type: string
- name: limit
in: query
description: Max events to return. Default 100, min 1, max 10000.
required: false
schema:
type: integer
default: 100
- name: offset
in: query
description: Events to skip for pagination. Default 0, min 0.
required: false
schema:
type: integer
default: 0
- 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: List of events and total count for pagination
content:
application/json:
schema:
$ref: '#/components/schemas/getEventsList'
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/GetEventsRequestBadRequestError'
'401':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/GetEventsRequestUnauthorizedError'
'500':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/GetEventsRequestInternalServerError'
post:
operationId: createEvent
summary: Create an event
description: Create an event to track a contact's interaction.
tags:
- event
parameters:
- 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:
'204':
description: Event posted
content:
application/json:
schema:
type: object
properties: {}
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEventRequestBadRequestError'
'401':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEventRequestUnauthorizedError'
requestBody:
content:
application/json:
schema:
type: object
properties:
contact_properties:
type: object
additionalProperties:
$ref: '#/components/schemas/EventsPostRequestBodyContentApplicationJsonSchemaContactProperties'
description: >-
Properties defining the state of the contact associated to this event. Useful to update contact
attributes defined in your contacts database while passing the event. For example: **"FIRSTNAME":
"Jane" , "AGE": 37**
event_date:
type: string
format: date-time
description: >-
ISO 8601 timestamp of when the event occurred (e.g. "2024-01-24T17:39:57+01:00"). If no value is
passed, the timestamp of the event creation is used.
event_name:
type: string
description: >-
The name of the event that occurred. This is how you will find your event in Brevo. Limited to 255
characters; only alphanumeric characters, hyphens (-), and underscores (_) are allowed.
event_properties:
type: object
additionalProperties:
$ref: '#/components/schemas/EventsPostRequestBodyContentApplicationJsonSchemaEventProperties'
description: >-
Properties of the event. Top level properties and nested properties can be used to better segment
contacts and personalise workflow conditions. The following field types are supported: string,
number, boolean (true/false), date (Timestamp e.g. "2024-01-24T17:39:57+01:00"). Keys are limited to
255 characters, alphanumerical characters and - _ only. Size is limited to 50KB.
identifiers:
$ref: '#/components/schemas/EventsPostRequestBodyContentApplicationJsonSchemaIdentifiers'
description: Identifies the contact associated with the event. At least one identifier is required.
object:
$ref: '#/components/schemas/EventsPostRequestBodyContentApplicationJsonSchemaObject'
description: >-
Identifiers of the object record associated with this event. Ignored if the object type or
identifier for this record does not exist on the account.
required:
- event_name
- identifiers
/events/batch:
post:
operationId: createBatchEvents
summary: Create events in batch
description: Create multiple events to track contacts' interactions in a single request.
tags:
- event
parameters:
- 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 accepted - all events have been added to the processing queue
content:
application/json:
schema:
$ref: '#/components/schemas/batchAcceptedResponse'
'400':
description: Bad request - all events in the batch failed validation
content:
application/json:
schema:
$ref: '#/components/schemas/batchEventsResponse'
'401':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/CreateBatchEventsRequestUnauthorizedError'
requestBody:
content:
application/json:
schema:
type: object
properties:
events:
type: array
items:
$ref: '#/components/schemas/EventsBatchPostRequestBodyContentApplicationJsonSchemaEventsItems'
required:
- events
servers:
- url: https://api.brevo.com/v3
description: https://api.brevo.com/v3
components:
schemas:
GetEventsListEventsItems:
type: object
properties:
contact_id:
type: integer
format: int64
description: Contact ID associated with the event
event_date:
type: string
format: date-time
description: Date and time of the event
event_name:
type: string
description: Name of the event
event_filter_id:
type: string
description: Filter ID of the event
object_type:
type: string
description: Object type associated with the event
event_properties:
type: object
additionalProperties:
description: Any type
description: Event-level custom properties
contact_properties:
type: object
additionalProperties:
description: Any type
description: Contact-level properties at time of event
title: GetEventsListEventsItems
getEventsList:
type: object
properties:
events:
type: array
items:
$ref: '#/components/schemas/GetEventsListEventsItems'
description: List of matching events ordered by event_date descending
count:
type: integer
format: int64
description: Total count of events matching the filters (use for pagination)
required:
- count
description: Response containing a list of events and the total count for pagination
title: getEventsList
EventsGetResponsesContentApplicationJsonSchemaCode:
type: string
enum:
- invalid_parameter
- missing_parameter
- out_of_range
- campaign_processing
- campaign_sent
- document_not_found
- not_enough_credits
- permission_denied
- duplicate_parameter
- duplicate_request
- method_not_allowed
- unauthorized
- account_under_validation
- not_acceptable
- bad_request
- unprocessable_entity
- Domain does not exist
- Contact email not found
- Attribute not found
- Category id not found
- Invalid parameters passed
- Record(s) for identifier not found
- Returned when query params are invalid
- Returned when invalid data posted
- Feed not found
- Campaign ID not found
- api-key not found
- DMARC policy requires domain authentication
- DNS records not properly configured
- Invalid OTP code provided
- OTP code has expired
- Domain already exists in your account
- The sum of all IP weights must equal 100
- Authentication failed
- Insufficient credits
- Request already processed
description: Error code displayed in case of a failure
title: EventsGetResponsesContentApplicationJsonSchemaCode
GetEventsRequestBadRequestError:
type: object
properties:
code:
$ref: '#/components/schemas/EventsGetResponsesContentApplicationJsonSchemaCode'
description: Error code displayed in case of a failure
message:
type: string
description: Readable message associated to the failure
required:
- code
- message
title: GetEventsRequestBadRequestError
GetEventsRequestUnauthorizedError:
type: object
properties:
code:
$ref: '#/components/schemas/EventsGetResponsesContentApplicationJsonSchemaCode'
description: Error code displayed in case of a failure
message:
type: string
description: Readable message associated to the failure
required:
- code
- message
title: GetEventsRequestUnauthorizedError
GetEventsRequestInternalServerError:
type: object
properties:
code:
$ref: '#/components/schemas/EventsGetResponsesContentApplicationJsonSchemaCode'
description: Error code displayed in case of a failure
message:
type: string
description: Readable message associated to the failure
required:
- code
- message
title: GetEventsRequestInternalServerError
EventsPostRequestBodyContentApplicationJsonSchemaContactProperties:
oneOf:
- type: string
- type: integer
- type: boolean
title: EventsPostRequestBodyContentApplicationJsonSchemaContactProperties
EventsPostRequestBodyContentApplicationJsonSchemaEventProperties:
oneOf:
- type: string
- type: integer
- type: boolean
- type: object
additionalProperties:
description: Any type
- type: array
items:
description: Any type
title: EventsPostRequestBodyContentApplicationJsonSchemaEventProperties
EventsPostRequestBodyContentApplicationJsonSchemaIdentifiers:
type: object
properties:
contact_id:
type: integer
format: int64
description: >-
Internal unique contact ID. When present, this takes priority over all other identifiers for event
attribution and contact resolution.
email_id:
type: string
description: Email Id associated with the event
ext_id:
type: string
description: ext_id associated with the event
landline_number_id:
type: string
description: landline_number associated with the event
phone_id:
type: string
description: SMS associated with the event
whatsapp_id:
type: string
description: whatsapp associated with the event
description: Identifies the contact associated with the event. At least one identifier is required.
title: EventsPostRequestBodyContentApplicationJsonSchemaIdentifiers
EventsPostRequestBodyContentApplicationJsonSchemaObjectIdentifiers:
type: object
properties:
ext_id:
type: string
description: External object ID
id:
type: string
description: Internal object ID
description: Identifiers for the object.
title: EventsPostRequestBodyContentApplicationJsonSchemaObjectIdentifiers
EventsPostRequestBodyContentApplicationJsonSchemaObject:
type: object
properties:
identifiers:
$ref: '#/components/schemas/EventsPostRequestBodyContentApplicationJsonSchemaObjectIdentifiers'
description: Identifiers for the object.
type:
type: string
description: Type of object (e.g., subscription, vehicle, etc.)
description: >-
Identifiers of the object record associated with this event. Ignored if the object type or identifier for this
record does not exist on the account.
title: EventsPostRequestBodyContentApplicationJsonSchemaObject
EventsPostResponsesContentApplicationJsonSchemaCode:
type: string
enum:
- invalid_parameter
- missing_parameter
- out_of_range
- campaign_processing
- campaign_sent
- document_not_found
- not_enough_credits
- permission_denied
- duplicate_parameter
- duplicate_request
- method_not_allowed
- unauthorized
- account_under_validation
- not_acceptable
- bad_request
- unprocessable_entity
- Domain does not exist
- Contact email not found
- Attribute not found
- Category id not found
- Invalid parameters passed
- Record(s) for identifier not found
- Returned when query params are invalid
- Returned when invalid data posted
- Feed not found
- Campaign ID not found
- api-key not found
- DMARC policy requires domain authentication
- DNS records not properly configured
- Invalid OTP code provided
- OTP code has expired
- Domain already exists in your account
- The sum of all IP weights must equal 100
- Authentication failed
- Insufficient credits
- Request already processed
description: Error code displayed in case of a failure
title: EventsPostResponsesContentApplicationJsonSchemaCode
CreateEventRequestBadRequestError:
type: object
properties:
code:
$ref: '#/components/schemas/EventsPostResponsesContentApplicationJsonSchemaCode'
description: Error code displayed in case of a failure
message:
type: string
description: Readable message associated to the failure
required:
- code
- message
title: CreateEventRequestBadRequestError
CreateEventRequestUnauthorizedError:
type: object
properties:
code:
$ref: '#/components/schemas/EventsPostResponsesContentApplicationJsonSchemaCode'
description: Error code displayed in case of a failure
message:
type: string
description: Readable message associated to the failure
required:
- code
- message
title: CreateEventRequestUnauthorizedError
EventsBatchPostRequestBodyContentApplicationJsonSchemaEventsItemsContactProperties:
oneOf:
- type: string
- type: integer
title: EventsBatchPostRequestBodyContentApplicationJsonSchemaEventsItemsContactProperties
EventsBatchPostRequestBodyContentApplicationJsonSchemaEventsItemsEventProperties:
oneOf:
- type: string
- type: integer
- type: object
additionalProperties:
description: Any type
- type: array
items:
description: Any type
title: EventsBatchPostRequestBodyContentApplicationJsonSchemaEventsItemsEventProperties
EventsBatchPostRequestBodyContentApplicationJsonSchemaEventsItemsIdentifiers:
type: object
properties:
contact_id:
type: integer
format: int64
description: >-
Internal unique contact ID. When present, this takes priority over all other identifiers for event
attribution and contact resolution.
email_id:
type: string
description: Email Id associated with the event
ext_id:
type: string
description: ext_id associated with the event
landline_number_id:
type: string
description: landline_number associated with the event
phone_id:
type: string
description: SMS associated with the event
whatsapp_id:
type: string
description: whatsapp associated with the event
description: Identifies the contact associated with the event. At least one identifier is required.
title: EventsBatchPostRequestBodyContentApplicationJsonSchemaEventsItemsIdentifiers
EventsBatchPostRequestBodyContentApplicationJsonSchemaEventsItemsObjectIdentifiers:
type: object
properties:
ext_id:
type: string
description: External object ID
id:
type: string
description: Internal object ID
description: Identifiers for the object.
title: EventsBatchPostRequestBodyContentApplicationJsonSchemaEventsItemsObjectIdentifiers
EventsBatchPostRequestBodyContentApplicationJsonSchemaEventsItemsObject:
type: object
properties:
identifiers:
$ref: '#/components/schemas/EventsBatchPostRequestBodyContentApplicationJsonSchemaEventsItemsObjectIdentifiers'
description: Identifiers for the object.
type:
type: string
description: Type of object (e.g., subscription, vehicle, etc.)
description: >-
Identifiers of the object record associated with this event. Ignored if the object type or identifier for this
record does not exist on the account.
title: EventsBatchPostRequestBodyContentApplicationJsonSchemaEventsItemsObject
EventsBatchPostRequestBodyContentApplicationJsonSchemaEventsItems:
type: object
properties:
contact_properties:
type: object
additionalProperties:
$ref: '#/components/schemas/EventsBatchPostRequestBodyContentApplicationJsonSchemaEventsItemsContactProperties'
description: >-
Properties defining the state of the contact associated to this event. Useful to update contact attributes
defined in your contacts database while passing the event. For example: **"FIRSTNAME": "Jane" , "AGE": 37**
event_date:
type: string
description: >-
Timestamp of when the event occurred (e.g. "2024-01-24T17:39:57+01:00"). If no value is passed, the
timestamp of the event creation is used.
event_name:
type: string
description: >-
The name of the event that occurred. This is how you will find your event in Brevo. Limited to 255
characters, alphanumerical characters and - _ only.
event_properties:
type: object
additionalProperties:
$ref: '#/components/schemas/EventsBatchPostRequestBodyContentApplicationJsonSchemaEventsItemsEventProperties'
description: >-
Properties of the event. Top level properties and nested properties can be used to better segment contacts
and personalise workflow conditions. The following field type are supported: string, number, boolean
(true/false), date (Timestamp e.g. "2024-01-24T17:39:57+01:00"). Keys are limited to 255 characters,
alphanumerical characters and - _ only. Size is limited to 50Kb.
identifiers:
$ref: '#/components/schemas/EventsBatchPostRequestBodyContentApplicationJsonSchemaEventsItemsIdentifiers'
description: Identifies the contact associated with the event. At least one identifier is required.
object:
$ref: '#/components/schemas/EventsBatchPostRequestBodyContentApplicationJsonSchemaEventsItemsObject'
description: >-
Identifiers of the object record associated with this event. Ignored if the object type or identifier for
this record does not exist on the account.
required:
- event_name
- identifiers
title: EventsBatchPostRequestBodyContentApplicationJsonSchemaEventsItems
batchAcceptedResponse:
type: object
properties:
message:
type: string
description: Confirmation message indicating the batch was accepted
count:
type: integer
description: Number of events queued for processing
required:
- message
- count
description: Response returned when all events in the batch are accepted for async processing
title: batchAcceptedResponse
BatchEventsResponseErrorsItems:
type: object
properties:
eventIndex:
type: array
items:
type: integer
description: Index positions (0-based) of the events that caused the error
message:
type: string
description: Description of the error
title: BatchEventsResponseErrorsItems
batchEventsResponse:
type: object
properties:
status:
type: string
description: Status of the batch request
total_events:
type: integer
description: Total number of events submitted in the batch
successful_events:
type: integer
description: Number of events that were successfully processed
failed_events:
type: integer
description: Number of events that failed to be processed
errors:
type: array
items:
$ref: '#/components/schemas/BatchEventsResponseErrorsItems'
description: List of errors for the failed events
required:
- status
- total_events
- successful_events
- failed_events
- errors
description: Response returned when a batch of events is processed
title: batchEventsResponse
EventsBatchPostResponsesContentApplicationJsonSchemaCode:
type: string
enum:
- invalid_parameter
- missing_parameter
- out_of_range
- campaign_processing
- campaign_sent
- document_not_found
- not_enough_credits
- permission_denied
- duplicate_parameter
- duplicate_request
- method_not_allowed
- unauthorized
- account_under_validation
- not_acceptable
- bad_request
- unprocessable_entity
- Domain does not exist
- Contact email not found
- Attribute not found
- Category id not found
- Invalid parameters passed
- Record(s) for identifier not found
- Returned when query params are invalid
- Returned when invalid data posted
- Feed not found
- Campaign ID not found
- api-key not found
- DMARC policy requires domain authentication
- DNS records not properly configured
- Invalid OTP code provided
- OTP code has expired
- Domain already exists in your account
- The sum of all IP weights must equal 100
- Authentication failed
- Insufficient credits
- Request already processed
description: Error code displayed in case of a failure
title: EventsBatchPostResponsesContentApplicationJsonSchemaCode
CreateBatchEventsRequestUnauthorizedError:
type: object
properties:
code:
$ref: '#/components/schemas/EventsBatchPostResponsesContentApplicationJsonSchemaCode'
description: Error code displayed in case of a failure
message:
type: string
description: Readable message associated to the failure
required:
- code
- message
title: CreateBatchEventsRequestUnauthorizedError
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.