POST /interaction/v1/eventDefinitions

Create an Event Definition, which contains the name and data schema for an event. The resource uses this key when firing an event to send it to the appropriate journey. Typically, marketers create the event definition in the Journey Builder UI. Use this resource instead if you’re using a custom application for Journey Builder functionality. To call this resource, assign your API Integration the Automation | Interactions | Read scope.

JSON Parameters

The request body has the properties described in this table.

Name	Type	Description
`arguments`	Object	Contains filter criteria for the Event Definition. Only required for types other than event.
`arguments.criteria`	String	When the API call defines a filter template, use this parameter as a template when a user chooses and configures the Event Definition. If you aren’t defining an additional filter for the Event Definition, leave this empty.
`arguments.UseHighWatermark`	Boolean	Controls whether to use incremental processing. The default value is `true`.
`arguments.ResetHighWatermark`	Boolean	Controls the initial High Watermark value on the first run. The default value is `false`.
`category`	String	The category of the event type. The default value is `Event`.
`configuration`	Object	Optional configuration data for the event. Only required for types other than event.
`dataExtensionId`	String	Required. The ID for the data extension associated with the event. Events fired from the API write to this data extension. Required only when not providing a schema.
`dataExtensionName`	String	The read-only name of the data extension associated with the event. POST and PUT methods ignore this field.
`description`	String	A description of Event Definition.
`eventDefinitionKey`	String	Required. A unique ID for the Event Definition. Don't include special characters.
`iconUrl`	String	The URL to an icon displayed in Event Administration and the Journey Builder Canvas that identifies an Event Definition
`isVisibleInPicker`	Boolean	Indicates whether the Event Picker shows the Event Definition to users when configuring a journey. To see your Event Definition in Journey Builder, use true.
`metaData`	Object	Optional data describing the event and its configuration. Only required for types other than event.
`mode`	String	The mode to run the Event Definitions in. Possible values are `Production` and `Test`. The default value is `Production`.
`name`	String	Required. A name for your Event Definition that identifies the event.
`schedule`	String	Creates an automation run daily according to the defined schedule. The call automatically adds a Fire Event activity to the automation. This automation fires events from the data extension defined as part of the Event Definition. For more information, see Salesforce Help: Fire an Event.
`schema`	Object	Schema information for an event. The call uses this information to create a data extension associated with the Event Definition. Only required when not providing a dataExtensionId value. For more information, see Event Definition Schema.
`sendableCustomObjectField`	String	Defines the subscriber key or email address within a data extension. Required when defining a schema.
`sendableSubscriberField`	String	Indicates type of sendable subscriber field. The default value is `SubscriberKey`. This property is required if you define a schema.
`sourceApplicationExtensionId`	String	A link to the application extension that defines the configuration screens for this type. Journey Builder uses this ID to filter shared entry sources. For example, for the Event Definition to be visible in the Existing Entry sources panel in the UI, this field must be populated. To obtain this value, perform a GET eventDefinition on similar events in Journey Builder.
`type`	String	Required. `Event` represents the most generic type of Event Definition. Other possible values include `ContactEvent`, `DateEvent`, or `RestEvent`.

Usage

To create an event definition, send a POST request to the /interaction/v1/eventDefinitions endpoint.

Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
POST /interaction/v1/eventDefinitions
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
    "type": "Event",
    "name": "New event definition via API",
    "description": "",
    "mode": "Production",
    "eventDefinitionKey": "NeweventviaAPI",
    "dataExtensionId": "bde86cbc-49c7-4e4b-b405-944314c3fe9c",
    "iconUrl": "/events/images/customer.png",
    "isVisibleInPicker": true,
    "category": "Event"
}

The response includes information about the event definition.

{
    "id": "5f8cf53a-a8c2-4501-a174-8eb90439f853",
    "type": "APIEvent",
    "name": "New event definition via API",
    "description": "",
    "createdDate": "2025-08-05T15:14:15",
    "createdBy": 288647,
    "modifiedDate": "2025-08-05T15:14:15",
    "modifiedBy": 288647,
    "mode": "Production",
    "eventDefinitionKey": "NeweventviaAPI",
    "dataExtensionId": "bde86cbc-49c7-4e4b-b405-944314c3fe9c",
    "filterDefinitionId": "24b35a84-850d-45d7-a4de-dac9038b792d",
    "iconUrl": "/events/images/customer.png",
    "arguments": {
        "serializedObjectType": "ApiEvent",
        "eventDefinitionId": "5f8cf53a-a8c2-4501-a174-8eb90439f853",
        "eventDefinitionKey": "NeweventviaAPI",
        "dataExtensionId": "bde86cbc-49c7-4e4b-b405-944314c3fe9c"
    },
    "metaData": {},
    "interactionCount": 0,
    "isVisibleInPicker": true,
    "category": "Event",
    "publishedInteractionCount": 0,
    "automationId": "e16f4184-077e-444b-8531-eefe1a11b895"
}