Customer events API for churn monitoring

Send one customer event

POST https://churnor.vercel.app/api/v1/events accepts an external customer_id or user_id and an event name. Optional fields include timestamp, properties, and an idempotency key.

The identifiers below are illustrative request values.

curl -X POST https://churnor.vercel.app/api/v1/events \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"customer_id":"example_customer","event":"report_exported","idempotency_key":"example_delivery_1","properties":{"format":"csv"}}'

API keys are scoped to a product environment. The endpoint validates and stores an accepted event, then attempts scoring. Check the returned score_saved field: successful event storage can still have score_saved=false. Retry the same saved delivery to repair its score. No latency guarantee is implied.

Batch ingestion

POST /api/v1/events/batch accepts an events array with 1–1,000 events. Each item uses the single-event fields. Supply timestamps when importing historical activity and inspect the returned inserted and deduplicated counts.

{"events":[{"customer_id":"example_customer","event":"login","idempotency_key":"example_delivery_2"}]}

Customer identity and retries

Use a stable external customer ID across API requests, CSV imports, and billing deliveries. When both ID fields are supplied, customer_id takes precedence. The API accepts idempotency_key or event_id; keep the same value when retrying the same delivery to avoid duplicate storage.

Handle validation and authentication errors before retrying. Rate limits return HTTP 429. Your application controls when to send requests and how to retry failures.

Continue setup

Read the API reference, connect billing events, or learn how activity affects risk scores.