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

**Language:** en
**Audience:** developer
**TLDR:** Send every event as soon as it happens, never more than 30 minutes after, with _event_date in ISO 8601 with time and offset (or omit it for now): a date without time is stored as midnight and won't start a flow. Never resend an event to update it: send a new event with a new _event_id and keep the entity id (meeting, payment, order) in a parameter. Use catalog types, stable low-cardinality values, and an action event at the right moment for reminders.
**Search keywords:** best practices, event date, _event_date, timezone offset, ISO 8601, event id, duplicate event, must be unique, entity id, flow not triggering, automation not firing, real time, batch, backfill, reminder, meeting_reminder, reschedule, placeholder values, custom event, action event
**Related pages:** /platform-api/ingest-api/guide, /platform-api/ingest-api/errors, /platform-api/ingest-api/rate-limits, /platform/en/data-sources/event-best-practices, /platform/en/automations/flows/triggers-and-entry
**Docs index (every page):** https://docs.instasent.com/llms.txt
**This zone's index:** https://docs.instasent.com/platform-api/ingest-api/llms-full.txt
**This page:** https://docs.instasent.com/platform-api/ingest-api/best-practices/ (HTML) · https://docs.instasent.com/platform-api/ingest-api/best-practices.md (Markdown)

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](/platform/en/data-sources/event-best-practices), 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](/platform-api/ingest-api/guide#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](/platform-api/ingest-api/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:

```json
"_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_id` — `string`, required
  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 parameter` — `string`
  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:

```json
[
  {
    "_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](/platform-api/ingest-api/guide#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](/platform/en/automations/flows/triggers-and-entry#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. 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. 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. Cancel: send meeting\_canceled

Add **Meeting canceled** as an exit event of the reminder flow, so a cancellation stops any run still in progress.

```json
[
  {
    "_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.

> **Warning**: 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

| 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

- [Ingest API guide](/platform-api/ingest-api/guide) - Mental model, merge rules and the event time window.
- [Errors](/platform-api/ingest-api/errors) - Status codes, the partial-success body and what to retry.
- [Best practices for sending events](/platform/en/data-sources/event-best-practices) - The same rules, explained for the people who build the flows.

---

This is one page of the Instasent documentation. For the complete machine-readable index of every guide and API reference, fetch https://docs.instasent.com/llms.txt — start there for full context.
