Event Ingestion API

Ingest real-time customer events that trigger actions, journey enrollments, and cross-channel workflows.

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

/api/v1/events/ingest

---

POST /api/v1/events/ingest

Ingest a single customer event for real-time processing.

Roles: Any authenticated user (no role check — only requires valid tenant).

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:

1. Validation — The request body is validated against the Zod schema. Invalid events return a 400.
2. Event stream publish — The event is published to the internal event bus. If the stream is unavailable, processing continues (non-critical).
3. Trigger evaluation — Active trigger rules are loaded and evaluated against the event. Each matching trigger’s action is dispatched.
4. 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
500	Server Error	Internal processing error

---

See Also

• Events API — Batch event ingestion
• Triggers — Configure trigger rules
• Geofence Check — Location-based event triggers