Events
Ingest the events that drive referral qualification
Events are the raw material the qualification engine evaluates gates against. Every action a referred user takes — signup, onboarding milestones, a paid subscription — arrives here, whether it comes from an SDK, your server, or a connected integration.
The Event object
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier (a UUID). |
object | string | Always event. |
name | string | Event name, e.g. signup, subscription_started, completed_onboarding. |
referred_user_id | string | Your id for the referred end-user this event belongs to. |
referral_code | string | The referral code or link the user came in through (for attribution), if known. |
properties | object | Arbitrary properties gates can match on (e.g. plan: "paid"). |
timestamp | string (date-time) | When the event occurred, as supplied by you. |
idempotency_key | string | Optional dedup key supplied in the body (in addition to the header). |
source | string | Where the event came from: sdk, api, revenuecat, adapty, stripe, or segment. |
mode | string | test or live, determined by the API key. |
livemode | boolean | Whether the event exists in live mode. |
received_at | string (date-time) | When Invitebase received the event. |
Ingest an event
Records an event for a referred user. The endpoint is idempotent and accepts either key type, so you can send events from client SDKs (publishable key) or your server (secret key). Events are accepted for asynchronous processing and return 202 Accepted.
Accepts publishable keys.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | No | Retries with the same key return the original result. |
name | body | string | Yes | Event name, e.g. subscription_started. |
referred_user_id | body | string | Yes | Your id for the referred end-user. |
referral_code | body | string | No | The code the user came in through, if known. Used for attribution. |
properties | body | object | No | Properties gates can match on (e.g. plan, value, count). |
timestamp | body | string (date-time) | No | When the event occurred. Defaults to receipt time. |
idempotency_key | body | string | No | Optional dedup key in the body. |
curl https://api.invitebase.com/v1/events \
-H "Authorization: Bearer $INVITEBASE_SECRET_KEY" \
-H "Idempotency-Key: evt-usr_123-sub-2026-07-09" \
-H "Content-Type: application/json" \
-d '{
"name": "subscription_started",
"referred_user_id": "usr_123",
"referral_code": "ANDREW-3F9K",
"properties": { "plan": "paid" },
"timestamp": "2026-07-09T14:32:00Z"
}'Response — 202 Accepted:
{
"id": "4d7e9f2a-1b58-4c36-a0d9-8e5f3b6c2d14",
"object": "event",
"name": "subscription_started",
"referred_user_id": "usr_123",
"referral_code": "ANDREW-3F9K",
"properties": { "plan": "paid" },
"timestamp": "2026-07-09T14:32:00.000Z",
"idempotency_key": null,
"source": "api",
"mode": "test",
"livemode": false,
"received_at": "2026-07-09T14:32:01.000Z"
}Errors: 400 (malformed body), 401 (missing or invalid key), 429 (rate limited). See Errors.
If the event satisfies a campaign's qualification gate, the referral's gate_progress updates and — once all gates pass inside the window — the referral moves to validated and a Reward is created automatically.