Skip to main content

Ingest API

Send engagement events into kenbun programmatically. Events are queued for background processing and scored against your active rulesets. This is the primary endpoint for real-time event ingestion from your applications, marketing tools, and integrations.

POST /ingest​

Queue an event for processing. The server acknowledges receipt immediately with 202 Accepted and processes the event asynchronously.

Request Body​

FieldTypeRequiredDescription
lead_idstringNoLead identifier. Required if no alias is provided
alias_kindstringNoType of alias: email, external_id, phone, cookie, or social
aliasstringNoAlias value corresponding to alias_kind
event_typestringYesType of event (e.g., Page View, Email Open, Form Submit)
timestampstringNoEvent timestamp in RFC 3339 format. Defaults to current time
metadataobjectNoAdditional key-value data to attach to the event

Provide either lead_id or both alias_kind and alias. If only an alias is supplied, a lead is created or resolved automatically.

{
  "alias_kind": "email",
  "alias": "user@example.com",
  "event_type": "Page View",
  "metadata": {
    "path": "/pricing",
    "utm_source": "google"
  }
}

Response​

202 Accepted

The event has been queued for processing.

Examples​

Ingest using email alias:

curl -X POST "https://api.kenbun.io/ingest" \
  -H "Authorization: Basic <credentials>" \
  -H "Content-Type: application/json" \
  -d '{
    "alias_kind": "email",
    "alias": "user@example.com",
    "event_type": "Page View"
  }'

Ingest with lead ID and metadata:

curl -X POST "https://api.kenbun.io/ingest" \
  -H "Authorization: Basic <credentials>" \
  -H "Content-Type: application/json" \
  -d '{
    "lead_id": "ld_abc123",
    "event_type": "Demo Request",
    "metadata": {"product": "enterprise", "source": "website"}
  }'

Ingest with a specific timestamp:

curl -X POST "https://api.kenbun.io/ingest" \
  -H "Authorization: Basic <credentials>" \
  -H "Content-Type: application/json" \
  -d '{
    "alias_kind": "email",
    "alias": "user@example.com",
    "event_type": "Email Open",
    "timestamp": "2025-09-15T14:30:00Z"
  }'

Common Errors​

StatusMeaningSolution
400Bad RequestActive OU must be set, or required fields are missing
401UnauthorizedCheck authentication credentials

Setting the Active OU​

The ingest endpoint requires an active Organizational Unit. Set it before ingesting events:

# 1. Set the active OU
curl -X POST "https://api.kenbun.io/org-units/active" \
  -H "Authorization: Basic <credentials>" \
  -H "Content-Type: application/json" \
  -d '{"ouId": "unit_default"}'

# 2. Ingest an event (OU is now set via cookie)
curl -X POST "https://api.kenbun.io/ingest" \
  -H "Authorization: Basic <credentials>" \
  -H "Content-Type: application/json" \
  -d '{"alias_kind": "email", "alias": "user@example.com", "event_type": "Page View"}'

Notes​

  • Events are processed asynchronously after acknowledgment
  • The organization and OU are determined from your authentication context -- do not send unit_id in the request body
  • If no active OU is set, the endpoint returns 400 with the message "active OU not set"
  • Events are scored against all active rulesets and may trigger milestone or sequence triggers
  • For bulk historical imports, consider the Import Events endpoint instead