The Event Ingestion API accepts typed customer events, publishes them to the internal event stream, and evaluates them against active trigger rules in real time. When a trigger matches, its configured action is dispatched automatically.
This endpoint is separate from the batch Events API. Use this for real-time, single-event ingestion from mobile apps, websites, and backend services. Base Path
POST /api/v1/events/ingest
Ingest a single customer event for real-time processing.
Roles: admin, editor
Request Body
| Field | Type | Required | Description |
|---|
type | string | Yes | Event type. One of: purchase, cart_abandon, page_view, app_open, support_call |
customerId | string | Yes | Customer identifier |
data | object | No | Arbitrary event properties (e.g., product ID, amount, page URL) |
channel | string | No | Source channel (e.g., web, mobile, pos) |
timestamp | string | No | ISO 8601 timestamp. Defaults to server time if omitted |
Event Types
| Type | Description | Internal Mapping |
|---|
purchase | Customer completed a purchase | Also evaluates triggers for outcome.recorded |
cart_abandon | Customer abandoned their cart | Also evaluates triggers for customer.updated |
page_view | Customer viewed a page | Behavioral event only |
app_open | Customer opened the mobile app | Behavioral event only |
support_call | Customer contacted support | Also evaluates triggers for customer.updated |
Each event type is mapped to one or more internal trigger event types. This means a single purchase event can fire both purchase-specific triggers and broader outcome.recorded triggers.
Response 200
{
"ingested": true,
"eventType": "purchase",
"customerId": "CUST-001",
"streamId": "evt_abc123def",
"triggersMatched": [
{
"triggerId": "tr_001",
"actionType": "recommend"
},
{
"triggerId": "tr_002",
"actionType": "journey_enroll"
}
],
"actionsDispatched": [
{
"triggerId": "tr_001",
"actionType": "recommend",
"config": { "decisionFlowId": "df_upsell", "channel": "push" }
},
{
"triggerId": "tr_002",
"actionType": "journey_enroll",
"config": { "journeyId": "j_post_purchase" }
}
]
}
Response Fields
| Field | Type | Description |
|---|
ingested | boolean | Always true on success |
eventType | string | The event type that was ingested |
customerId | string | The customer identifier |
streamId | string or null | Event stream ID (null if stream publish failed — event is still processed) |
triggersMatched | array | Trigger rules that matched this event |
actionsDispatched | array | Actions that were successfully dispatched |
actionErrors | array | (Only present if errors occurred) Actions that failed to dispatch |
Example
# Purchase event with metadata
curl -X POST https://playground.kaireonai.com/api/v1/events/ingest \
-H "X-Tenant-Id: my-tenant" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <token>" \
-d '{
"type": "purchase",
"customerId": "CUST-001",
"channel": "pos",
"data": {
"orderId": "ORD-789",
"amount": 49.99,
"productId": "SKU-456",
"storeId": "STORE-01"
}
}'
# Cart abandonment from web
curl -X POST https://playground.kaireonai.com/api/v1/events/ingest \
-H "X-Tenant-Id: my-tenant" \
-H "Content-Type: application/json" \
-d '{
"type": "cart_abandon",
"customerId": "CUST-002",
"channel": "web",
"data": {
"cartValue": 129.99,
"itemCount": 3,
"abandonedUrl": "/checkout"
}
}'
Processing Pipeline
When an event is ingested, the following happens in order:
- Validation — The request body is validated against the Zod schema. Invalid events return a
400.
- Event stream publish — The event is published to the internal event bus. If the stream is unavailable, processing continues (non-critical).
- Trigger evaluation — Active trigger rules are loaded and evaluated against the event. Each matching trigger’s action is dispatched.
- Response — The API returns the ingestion result with matched triggers and dispatched actions.
Event stream publish failures are non-critical and will not cause the API to return an error. The event is still evaluated against triggers. Check the streamId field — a null value indicates the stream publish failed.
Cross-Channel Triggers
Event ingestion powers cross-channel workflows. For example:
| Event Source | Trigger Action | Result |
|---|
POS purchase | recommend via push channel | Customer gets a push notification with a related offer |
Web cart_abandon | journey_enroll | Customer enters a 3-step email recovery journey |
App app_open | recommend via in-app channel | Customer sees personalized offers on the home screen |
Support support_call | Webhook notification | CRM system is updated with the interaction |
Error Codes
| Status | Code | Description |
|---|
400 | Bad Request | Invalid event type or missing customerId |
401 | Unauthorized | Missing or invalid authentication |
403 | Forbidden | Insufficient role |
500 | Server Error | Internal processing error |
See Also
