Custom events in scenarios
This POST method allows you to trigger scenario custom events for individual customers or entire customer segments.
POST – trigger custom event for single customer
Use this method to trigger events for a single customer identified by email, phone, CRM ID, or customer ID.
Endpoint
The endpoint (server address) for this request is https://api.ecdp.app/scenariocustomevents
Request parameters
| Parameter | Location | Type | Required | Description | Allowed values / Notes |
| x-api-key | header | string | yes | Your API key from Settings > API. | – |
| customEventId | body | integer | yes | The unique identifier of the custom event to trigger. | Must be a valid custom event ID configured in your business unit in Automation > Scenarios > Custom events tab. |
| customerId | body | string | no | The internal ECDP customer ID. | At least one customer identifier is required. |
| customerEmail | body | string | no | The customer’s email address. | Max 320 characters. At least one customer identifier is required. |
| customerEmailMd5 | body | string | no | The customer’s email address hashed with MD5. | Max 32 characters. At least one customer identifier is required. |
| customerEmailSha256 | body | string | no | The customer’s email address hashed with SHA-256. | Max 64 characters. At least one customer identifier is required. |
| customerPhone | body | string | no | The customer’s phone number. | Max 20 characters. At least one customer identifier is required. |
| customerCrmId | body | string | no | The customer’s CRM ID from your external system. | Max 128 characters. At least one customer identifier is required. |
| dataFields | body | array | no | Additional data describing the custom event. | Array of data fields. See Data fields below. |
Data fields
The dataFields array allows you to pass additional context data with the custom event. Each data filed in the array contains:
| Parameter | Location | Type | Required | Description | Allowed values |
| name | body | string | no | The name of the data field. | Any valid string identifier. |
| type | body | string | no | The data type of the field value. | String, Text, Number, Money, Date, DateTime, Boolean, URL |
| value | body | string | no | The value of the data field. | Must match the specified type format. |
Response codes
| Code | Status | Description |
| 201 | Created | The custom event was triggered successfully. |
| 400 | Bad Request | The request was not processed due to missing or invalid parameters. |
| 401 | Unauthorized | The API key is missing or invalid. |
| 404 | Not Found | The specified custom event ID or customer was not found. |
| 500 | Internal Server Error | An unexpected server error occurred. |
Example requests and responses
Trigger a specific event for a single customer
Request body:
{
"customEventId": 42,
"customerEmail": "jan.kowalski@example.com"
}Response:201 Created
Trigger an event for a single customer that meets specific criteria
Request body:
{
"customEventId": 42,
"customerEmail": "anna.nowak@example.com",
"customerCrmId": "CRM-2024-00158",
"dataFields": [
{
"name": "productCategory",
"type": "String",
"value": "Electronics"
},
{
"name": "purchaseAmount",
"type": "Money",
"value": "299.99"
},
{
"name": "purchaseDate",
"type": "DateTime",
"value": "2024-12-15T14:30:00Z"
}
]
}Response:201 Created
POST – trigger custom event for a segment
Use this method to trigger events for all customers within specified segments.
Endpoint
The endpoint (server address) for this request is https://api.ecdp.app/scenariocustomevents/withsegments
Request parameters
| Parameter | Location | Type | Required | Description | Allowed values / Notes |
| x-api-key | header | string | yes | Your API key from Settings > API. | – |
| customEventId | body | integer | yes | The unique identifier of the custom event to trigger. | Must be a valid custom event ID configured in your business unit. |
| segments | body | array of integers | yes | The list of segment IDs to include. | At least one segment ID is required. All segments must exist. |
| dataFields | body | array | no | Additional data describing the custom event. | Array of data field objects. See Data Fields Parameters above. |
Response codes
| Code | Status | Description |
| 201 | Created | The custom event was triggered for all customers in the specified segments. |
| 400 | Bad Request | The request was not processed due to missing or invalid parameters. |
| 401 | Unauthorized | The API key is missing or invalid. |
| 404 | Not Found | The specified custom event ID or one of the segments was not found. |
| 500 | Internal Server Error | An unexpected server error occurred. |
Example requests and responses
Trigger a specific event for a selected customer segment
Request body:
{
"customEventId": 42,
"segments": [15]
}Response: 201 Created
Trigger an event for a a selected customer segment that includes specific attributes
Request body:
{
"customEventId": 42,
"segments": [1, 5, 15],
"dataFields": [
{
"name": "campaignName",
"type": "String",
"value": "Winter Sale 2024"
},
{
"name": "discountPercentage",
"type": "Number",
"value": "25"
},
{
"name": "validUntil",
"type": "Date",
"value": "2024-12-31"
}
]
}Response:201 Created
Validation and behavior rules
- At least one customer identifier (customerId, customerEmail, customerEmailMd5, customerEmailSha256, customerPhone, or customerCrmId) is required for the single customer endpoint.
- The customEventId must reference an existing custom event configured in your business unit in Automation > Campaign > Events tab.
- For segment-based triggering, at least one valid segment ID must be provided.
- The dataFields array is optional; when omitted, the custom event is triggered without additional context data.
Reference documentation
Swagger – Scenario custom events