{"openapi":"3.1.0","info":{"title":"Events","version":"1.0.0"},"paths":{"/events":{"get":{"operationId":"getEvents","summary":"Get events","description":"<Note>\nThis endpoint currently only supports custom events.\n</Note>\n\nRetrieve 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."}}}}