Platform API · Ingest API
Ingest API best practices
How to send events so flows, segments and reports can use them: the event date and its offset, event ids versus entity ids, contact identification, real time versus batches, parameter values, the reminder pattern and the mistakes that silently stop a flow.
Every event you send is stored on the contact's timeline, but only events that arrive the right way can start a flow, end one, or be filtered on reliably. Most integrations that "don't trigger anything" break one of a few rules: a date without a time, an event sent hours late, an id reused to update a record, or a parameter whose values change spelling from one day to the next. This page collects those rules and the patterns that follow from them. It is the developer side of Best practices for sending events, the guide your marketing team reads in the Platform docs.
Send events as they happen
Flows only react to events that are current. The Ingest API checks how far _event_date is from the moment the event is processed, which includes the time it waits in the queue after the request is accepted; the exact window and why it exists are explained in Automations and the event time window. An event dated outside it is stored and usable in segments and reports, but it never starts a flow, and the same rule applies when the event should end a flow, satisfy a wait or count as a goal.
The recommendation, for every event a flow may need: send it as soon as it happens, and never more than 30 minutes after. That leaves room for retries without getting near the edge of the window. Events dated in the future are treated the same way as late ones: a producer whose clock runs ahead, or an event dated at the moment something is scheduled to happen, starts nothing.
Batches are fine; delayed batches are not
POST /stream/events accepts up to 100 items per call, and grouping items is the right way to stay inside the rate limits. Group what is already happening: flush a buffer every few seconds, or when it reaches 100 items. A job that collects the day's events and sends them hourly or nightly turns every event into a late one, and none of them will start a flow.
Loading history is a different job. Send historical events with their real dates: they enrich the timeline, segments and reports, and they never fire a flow, which is what you want. The first sync of a newly connected source, CSV imports and manual imports never start flows either.
The event date
_event_date is optional. When you send it, it must carry a time and a timezone offset in ISO 8601:
"_event_date": "2026-11-12T17:42:00+01:00"- Omit it for events you send in real time: it defaults to the moment of reception, which is always inside the window.
- Never send a date without a time (
"2026-11-12"). It is stored as midnight, which almost never falls inside the window, so the flow silently does not start. - Always include the offset (
+01:00,Z). A time without an offset is read as UTC, so a local time can land outside the window. - Use the moment the event happened, not the moment something is planned for. When a meeting is booked for next Tuesday, the
meeting_registeredevent is dated now; Tuesday goes in the meeting's own date parameter.
Event ids and entity ids
Two different identifiers live on every event, and mixing them up is the most common integration bug:
_event_idstringrequiredIdentifies this event, once. The same _event_id with the same _event_type on the same datasource is rejected with 400 and a message ending in combination must be unique. That is what makes retries safe: resend a failed event with the same _event_id and it can't be stored twice. A 400 … combination must be unique on a retry means the first attempt was stored.
Entity id parameterstringIdentifies the thing the event is about: the meeting, the payment, the order. It goes in the type's own parameter (id for a meeting, payment-id for a payment) and stays the same across every event about that entity, so its history can be followed.
Never resend an event to update it. Events are immutable: a second event with the same _event_id is rejected, not merged. When the state of something changes, send a new event with a new _event_id that carries the new state, and keep the same entity id in its parameter:
[
{
"_user_id": "CUSTOMER-123",
"_event_id": "MTG-5521-registered",
"_event_type": "meeting_registered",
"_event_date": "2026-11-12T17:42:00+01:00",
"_event_parameters": { "id": "MTG-5521", "date": "2026-11-18T10:00:00+01:00", "type": "demo" }
},
{
"_user_id": "CUSTOMER-123",
"_event_id": "MTG-5521-canceled",
"_event_type": "meeting_canceled",
"_event_date": "2026-11-14T09:05:00+01:00",
"_event_parameters": { "id": "MTG-5521", "date": "2026-11-18T10:00:00+01:00", "type": "demo" }
}
]Identify the contact
Every event must belong to a contact. Send its _user_id (the same identifier you use for that person in POST /stream/contacts), or embed the contact with _user_data when your system produces both at once. An event whose contact doesn't exist yet is rejected; the guide explains how to handle it in Sending a new contact and its event together. An event that can't be tied to a contact can't be used by flows or segments.
Event types
Prefer a catalog type whenever one fits: payment, ecommerce_order_create, meeting_registered, deal_won and the rest listed by GET /stream/specs/events. Catalog types come with known parameters that the dashboard, flows and reports already understand.
actioncarries a freeactionname ("action": "meeting_reminder") and can start a flow. It is the right type for a moment your system decides, such as a reminder.customis for something no type describes; it can start a flow too, but it carries no shared meaning.- Some types never start a flow, whatever their date: Order updated (
ecommerce_order_update), Checkout cancelled (ecommerce_checkout_cancel),generic,metric, contact bookkeeping (created, merged, deleted) and Instasent's own records of its messages.leadandappointmentcan.
Some sources never trigger flows whatever the type, CSV imports among them. The full list of events that can start a flow, as the dashboard shows it, is in Which events can start a flow.
Parameter values
Flows filter and branch on parameter values, and segments do the same. A few rules keep those filters honest:
- No placeholders.
"#none","","-","N/A"and"null"all count as no value. Leave the parameter out instead of filling it with one of them. - One vocabulary, forever. Status-like parameters need one stable set of values:
attendedevery time, neverattendedone day,Attendedthe next andAsistióafter a translation change. A flow condition matches one spelling. - Low cardinality is what flows use. Statuses, categories, types and yes/no values are what a trigger condition or a branch filters on. Free text and ids are useful on the timeline, not as filter material.
- Respect the type. Send amounts as numbers, booleans as booleans, dates with time and offset, and currencies as ISO 4217 codes (
EUR).
Pattern: reminders before a date
A flow can wait a fixed time (from 1 minute to 90 days) after something happens, but it can't wait until a date carried in an event, such as "24 hours before the meeting". A Wait for activity step also counts only events dated after the wait started. Scheduled triggers in flows are coming soon; until then, the reminder moment comes from your system:
Book: send meeting_registered
When the meeting is booked, send
meeting_registeredwith the meeting'sidanddate. Use Appointment (appointment) for the booking itself if that type fits your business better.Remind: send an action at the exact moment
At the moment the reminder must go out (for example, 24 hours before the meeting), send an
actionevent with"action": "meeting_reminder", dated now, carrying the meetingidanddate. The flow triggers on Action performed with the conditionactionequalsmeeting_reminderand sends the message straight away.Cancel: send meeting_canceled
Add Meeting canceled as an exit event of the reminder flow, so a cancellation stops any run still in progress.
[
{
"_user_id": "CUSTOMER-123",
"_event_id": "MTG-5521-reminder-24h",
"_event_type": "action",
"_event_parameters": {
"action": "meeting_reminder",
"id": "MTG-5521",
"date": "2026-11-18T10:00:00+01:00"
}
}
]Rescheduling is three events: meeting_canceled for the old meeting, a new meeting_registered for the new date, and the reminder sent at the new time. Stop sending the reminder scheduled for the old date in your system: Instasent has no way of knowing it is stale.
Common mistakes
| Mistake | What happens | Fix |
|---|---|---|
_event_date without a time (2026-11-12) | Stored as midnight; the flow never starts | Send time and offset, or omit the date |
| A local time without offset | Read as UTC, so it can land outside the window | Always include the offset (+01:00, Z) |
| Events collected and sent hourly or nightly | Stored, but none of them start a flow | Send as they happen; batch only within seconds |
| Dating an event at the moment it is scheduled for | A future date; nothing starts | Date it when it happens; put the planned date in a parameter |
Resending an event with the same _event_id to update it | 400 … combination must be unique; the update is lost | Send a new event with a new _event_id and the same entity id |
Placeholder values ("N/A", "-") | Count as no value; conditions don't match | Leave the parameter out |
| Status values with changing spelling | The flow condition matches only some events | Keep one stable vocabulary |
Using generic or metric for something a flow needs | Stored, but never starts a flow | Use a catalog type, action or custom |
| Expecting a CSV import or the first sync to trigger | Nothing starts, by design | Send live events through the API |
What to read next
Last updated