Overview
Send inbound contact events that trigger journeys via the API
An event is something that happened in one of your own systems — a cart abandoned, an order placed, a form submitted — that you want Lemu to know about. Sending one resolves or creates a contact by phone number and can trigger any journey with a matching API Events trigger.
| Method | Endpoint | Purpose |
|---|---|---|
POST | /events | Ingest an inbound event and trigger matching journeys |
GET | /events | List recent events for the organization, newest first |
Ingest an event#
curl -X POST https://app.lemuai.com/api/v1/events \
-H "X-API-Key: lemu_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"event_type": "order_placed",
"phone": "+14155550100",
"list_name": "Recent buyers",
"data": {
"order_id": "ORD-4821",
"cart_amount": 2499,
"product_name": "safari-14"
}
}'Request body#
| Field | Type | Required | Description |
|---|---|---|---|
event_type | string | Yes | Identifies the event, e.g. cart_added, order_placed. Matched against journeys' API Events triggers |
phone | string | No | Contact's phone number — used to resolve or create the contact |
list_name | string | No | If set, upserts the contact into this list (creating it if it doesn't exist) |
data | object | No | Arbitrary key-value payload. Available as context variables inside triggered journey runs |
Response — 201 Created
| Field | Type | Description |
|---|---|---|
event_id | integer | Unique ID of the stored event |
contact_id | integer | null | ID of the resolved or upserted contact. null if no phone was provided |
triggered_workflows | integer | Always 0 — matching journeys are triggered asynchronously, not synchronously with this response |
If phone resolves to a brand-new contact, it's created and tagged event so it's easy to find in the CRM, and it counts against your plan's CRM contacts limit. If your organization is at that limit, the event is still stored and still triggers journeys — the contact link is just left unset.
List events#
GET /events powers the Event Log page and returns events newest-first, with the same filters the page's UI exposes.
| Query param | Description |
|---|---|
event_type | Filter to one event type |
search | Match against phone, contact name, or event type |
start_date / end_date | Inclusive date range, YYYY-MM-DD or ISO datetime |
limit / offset | Pagination, limit up to 500 |
unique_by_phone | Collapse to one row per distinct phone number (most recent event only) |
curl "https://app.lemuai.com/api/v1/events?event_type=order_placed&limit=50" \
-H "X-API-Key: lemu_your_api_key"{
"events": [
{
"id": 48213,
"event_type": "order_placed",
"phone": "+14155550100",
"contact_id": 9182,
"contact_name": "Ana Ray",
"event_data": { "order_id": "ORD-4821", "cart_amount": 2499 },
"created_at": "2026-09-23T11:26:00Z"
}
],
"total": 1
}