openapi: 3.2.0
info:
  title: Events Event API
  version: 1.0.0
servers:
- url: https://api.brevo.com/v3
  description: https://api.brevo.com/v3
tags:
- name: event
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
components:
  schemas:
    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
    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
    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
    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
    EventsPostRequestBodyContentApplicationJsonSchemaContactProperties:
      oneOf:
      - type: string
      - type: integer
      - type: boolean
      title: EventsPostRequestBodyContentApplicationJsonSchemaContactProperties
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    EventsPostRequestBodyContentApplicationJsonSchemaEventProperties:
      oneOf:
      - type: string
      - type: integer
      - type: boolean
      - type: object
        additionalProperties:
          description: Any type
      - type: array
        items:
          description: Any type
      title: EventsPostRequestBodyContentApplicationJsonSchemaEventProperties
    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
  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.