Track events
Record what people do, with properties you can filter on
Request
POST /v1/events/track with the project key and the user's id. event_name is the only required field.
curl -X POST https://api.iforevents.com/v1/events/track \
-H "X-Project-Key: <project key>" \
-H "X-User-Id: user-123" \
-H "Content-Type: application/json" \
-d '{"event_name":"checkout_completed","event_type":"track","properties":{"plan":"pro","amount":"79"}}'| Field | Required | Notes |
|---|---|---|
event_name | yes | Snake case works best: page_view, checkout_completed |
event_type | no | track (default), page_view or identify |
properties | no | Flat object; values stored as strings |
header X-User-Id | recommended | Who the event belongs to: your id for the person, or an anonymous id you keep per visitor (any string, up to 256 characters). Without it the event lands on a profile derived from the caller's address, shared by everyone behind the same NAT or server; see Tracking |
Answer: 201 Created.
Batches
Send up to 500 events in one request when you buffer client side or import history:
curl -X POST https://api.iforevents.com/v1/events/batch \
-H "X-Project-Key: <project key>" \
-H "X-User-Id: user-123" \
-H "Content-Type: application/json" \
-d '{"events":[
{"name":"page_view","type":"page_view","properties":{"page":"/"}},
{"name":"button_click","properties":{"button":"signup"},"created_at":"2026-09-11T12:00:00Z"}
]}'Batch items use name, type, properties and an optional created_at timestamp; the whole batch belongs to the user in X-User-Id. The API answers 202 Accepted and processes the batch in the background.
Naming advice
- One verb per event:
signup_completed, notuser. - Put variants in properties (
plan: pro), not in names (signup_pro). - Keep names under 64 characters; the dashboard groups by exact name.
In the Flutter SDK
iforevents.track(
event: TrackEvent(
eventName: 'checkout_completed',
properties: {'plan': 'pro', 'amount': 79},
),
);Events are queued and sent in batches; the queue survives app restarts and retries on failure. The SDK sends X-User-Id itself: an anonymous id it generates on first launch, or the customID given to identify.