> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kaireonai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Info>
  This endpoint is separate from the batch [Events API](/api-reference/events). Use this for real-time, single-event ingestion from mobile apps, websites, and backend services.
</Info>

## 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` |

<Note>
  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.
</Note>

### Response `200`

```json theme={null}
{
  "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

```bash theme={null}
# 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"
    }
  }'
```

```bash theme={null}
# 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.

<Warning>
  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.
</Warning>

***

## 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](/api-reference/events) -- Batch event ingestion
* [Triggers](/api-reference/triggers) -- Configure trigger rules
* [Geofence Check](/api-reference/geofences) -- Location-based event triggers