Skip to main content
Use this guide to integrate event submission safely and predictably. For the canonical event types, action values, status values, and tag mappings, see Event vocabulary.

​
1) Build A Valid Event Payload

Required:
  • type
  • at least one contact identifier: email or uid
Common optional fields:
  • source
  • action
  • feature
  • plan
  • amount
  • status
  • upgrade
  • idempotency_key
  • external_id
  • ts
  • metadata
Example payload: 
{
	"email": "buyer@example.com",
	"type": "purchase",
	"source": "api",
	"action": "renewed",
	"feature": "billing",
	"plan": "pro",
	"amount": 49.9,
	"status": "success",
	"upgrade": false,
	"idempotency_key": "purchase-buyer-example-com-20260622",
	"ts": "2026-06-22T10:30:00Z"
}

​
2) Send The Event

Single event endpoint:
  • POST /api/v1/client/events
Bulk endpoint:
  • POST /api/v1/client/events/bulk
Request example: 
curl -X POST "https://your-api-domain/api/v1/client/events" \
	-H "Authorization: Bearer <token>" \
	-H "Content-Type: application/json" \
	-d '{
		"email": "buyer@example.com",
		"type": "purchase",
		"status": "success",
		"idempotency_key": "purchase-buyer-example-com-20260622"
	}'

​
3) Expect Async Processing

  1. Client sends event payload.
  2. API accepts request.
  3. Event enters incoming inbox processing.
  4. On success, canonical event is created.
  5. On failure, inbox shows error and retry state.
Typical behavior:
  • create may return accepted or success depending on sync mode and environment behavior
  • canonical event may appear shortly after inbox entry

​
4) Verify In Incoming Events

Use:
  • GET /api/v1/public/authenticated/events/incoming
Check fields:
  • status
  • process_error
  • retryable
  • retry_count
  • event_id
When event_id is present, the canonical event is linked.

​
5) Verify In Canonical Events

Use:
  • GET /api/v1/public/authenticated/events
Use filters such as:
  • event_type
  • source
  • status
  • from
  • to
  • q

​
6) Idempotency Strategy

Use a deterministic key for retriable client operations. Recommended key pattern:
  • <event_type>-<contact_identifier>-<logical_event_time_or_sequence>
Example:
  • purchase-user_123-20260622T103000Z

​
7) Polling Strategy

Recommended UI pattern:
  1. Load Events and Incoming Events in parallel.
  2. Poll Incoming Events every 5 to 15 seconds while page is visible.
  3. Stop polling when no rows are received or processing.

​
Common Integration Mistakes

  • missing contact identity fields
  • inconsistent event type naming across clients
  • non-deterministic idempotency keys
  • assuming canonical list updates instantly
  • ignoring terminal failures in incoming events