Docs
OverviewPlatformPlatform APIA2P Messaging API
AI & MCP
Open dashboard
OverviewPlatformPlatform APIA2P Messaging API
AI & MCP
  • Overview
  • Introduction
  • Create an account
  • Choose your API
  • Authentication
  • AI & MCP
Product API
  • Guide
  • Quickstart
    • API tokens
    • Connected apps (OAuth)
    • Project readiness
    • Channel readiness
    • Senders
    • Attention
    • Recommendations
    • Overview
    • Contacts and attributes
    • Events
    • Query filter
    • Event query filter
    • Probes
    • Counting and retrieval
    • Segments
    • Overview
    • Creating a draft
    • Editing a draft
    • Audience targeting
    • Message content
    • Dates and scheduling
    • Reading campaigns
    • Estimating and deleting
    • OverviewBeta
    • Templates
    • Creating and editing drafts
    • Triggers and exits
    • Nodes
    • Delays and waits
    • Overview
    • Statistics catalog
    • Building queries
    • Conversions & revenue
    • Reading results
    • Flow reports
    • Rate limits
    • Errors
  • Full API Reference
Ingest API
  • Guide
  • Quickstart
  • Authentication
  • Rate limits
  • Errors
  • Best practices
  • Full API Reference
Further reading
  • Query Filter
DashboardSupportinstasent.com

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.

On this page▾
  • Send events as they happen
  • Batches are fine; delayed batches are not
  • The event date
  • Event ids and entity ids
  • Identify the contact
  • Event types
  • Parameter values
  • Pattern: reminders before a date
  • Common mistakes
  • What to read next

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_registered event 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_idstringrequired

Identifies 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 parameterstring

Identifies 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.

  • action carries a free action name ("action": "meeting_reminder") and can start a flow. It is the right type for a moment your system decides, such as a reminder.
  • custom is 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. lead and appointment can.

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: attended every time, never attended one day, Attended the next and Asistió 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:

  1. 1

    Book: send meeting_registered

    When the meeting is booked, send meeting_registered with the meeting's id and date. Use Appointment (appointment) for the booking itself if that type fits your business better.

  2. 2

    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 action event with "action": "meeting_reminder", dated now, carrying the meeting id and date. The flow triggers on Action performed with the condition action equals meeting_reminder and sends the message straight away.

  3. 3

    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.

Exit events match by event type and by the fixed values in their conditions. They don't know which meeting or payment started a run. A meeting_canceled ends every run of that contact that listens for it, including the run for a different meeting the contact still has booked.

Common mistakes

MistakeWhat happensFix
_event_date without a time (2026-11-12)Stored as midnight; the flow never startsSend time and offset, or omit the date
A local time without offsetRead as UTC, so it can land outside the windowAlways include the offset (+01:00, Z)
Events collected and sent hourly or nightlyStored, but none of them start a flowSend as they happen; batch only within seconds
Dating an event at the moment it is scheduled forA future date; nothing startsDate it when it happens; put the planned date in a parameter
Resending an event with the same _event_id to update it400 … combination must be unique; the update is lostSend a new event with a new _event_id and the same entity id
Placeholder values ("N/A", "-")Count as no value; conditions don't matchLeave the parameter out
Status values with changing spellingThe flow condition matches only some eventsKeep one stable vocabulary
Using generic or metric for something a flow needsStored, but never starts a flowUse a catalog type, action or custom
Expecting a CSV import or the first sync to triggerNothing starts, by designSend live events through the API

What to read next

Ingest API guide

Mental model, merge rules and the event time window.

Errors

Status codes, the partial-success body and what to retry.

Best practices for sending events

The same rules, explained for the people who build the flows.

Last updated November 17, 2026

PreviousErrorsNextFull API Reference
  • Send events as they happen
  • Batches are fine; delayed batches are not
  • The event date
  • Event ids and entity ids
  • Identify the contact
  • Event types
  • Parameter values
  • Pattern: reminders before a date
  • Common mistakes
  • What to read next

© 2026 Instasent

Privacy PolicyTerms & ConditionsCookie PolicyLegal Notice
All systems operational