Ingest API guide

The Ingest API is the door that customer data walks through on its way into Instasent. Every contact you create, every event you record, lands in a project as a datasource and feeds the audience that your campaigns, segments and analytics read from.

It is a focused subset of the Product API: three write endpoints for contacts and events, plus a handful of read endpoints for validating your payloads against the datasource specs. If you already run Product API calls, the same tokens work here — see Authentication.

When to reach for it

Pick the Ingest API when an external system of record owns your customer data and Instasent needs a steady feed of it:

• CRM or e-commerce syncs — push new and updated contacts as your source platform mutates them.
• Product event streams — record purchases, sign-ups, page views or any custom interaction you want to segment on.
• Backfills — load historical data into a fresh project before flipping campaigns on.

If instead you need to read back an audience, trigger a campaign, or orchestrate messaging, that is the Product API's job.

Mental model

Three nouns and one rule of thumb:

• Contacts — the people in your audience. Identified by a _user_id that is unique within your datasource. Sending the same _user_id again updates the existing record.
• Events — time-stamped interactions tied to a contact (purchase, viewed_product, reservation_made, anything you define). Events are immutable once accepted.
• Datasource — the logical stream your API token writes to. A project can have several datasources, and when two disagree about the same contact, the Ingest datasource wins.

The rule of thumb: treat Ingest writes as idempotent for contacts and append-only for events. Your client should be safe to retry contact uploads; event uploads must use a stable _event_id so duplicates are rejected on our side.

A day in the life of a contact

1. 1

   Your CRM emits a change

   A new customer signs up, or an existing one updates their phone number. Your integration catches the change event.

2. 2

   POST /stream/contacts

   Send the contact — _user_id, identity fields, any custom attributes — as a single-item array. Omit attributes you do not own; nothing you leave out gets overwritten.

3. 3

   Instasent merges the record

   The request answers 202 Accepted as soon as the contact is queued. It is stored in the datasource shortly after, usually within a few seconds, and the audience view follows.

4. 4

   Later: POST /stream/events

   The same customer places an order. You POST a purchase event with _user_id and _event_parameters. The event lands on the contact's timeline and becomes queryable for segmentation.

Shape of the API

All endpoints live under https://api.instasent.com/v1/project/{project}/datasource/{datasource}/:

Per-parameter detail lives in the API Reference.

How contacts are merged

Attributes in a contact payload follow a few simple rules:

• Omitted attribute → existing value kept. Send partial updates without fear.
• Explicit null → attribute cleared.
• Same _user_id across datasources → contacts merge automatically into one audience record, and Ingest values take precedence when they collide.

How events flow

Two shapes for POST /stream/events:

• Event-only — just _user_id, _event_id, _event_type and _event_parameters. The contact must already be stored: if it does not exist, or is still being processed, the event is rejected (see below).
• Event with embedded contact — add _user_data to create or update the contact in the same call. Saves a round-trip when your source system can produce both at once.

_event_id must be stable and unique per event. An event whose _event_id is already stored for the same _event_type is rejected as a duplicate instead of being stored twice — that is what makes retries safe.

Sending a new contact and its event together

A contact sent to POST /stream/contacts is stored a moment after the 202 response, usually within a few seconds. An event-only request sent in that gap finds no contact and is rejected with 400 and a message ending in Contact with that id must be created prior sending any events (inside a batch where other items were accepted, it is listed in the errors of a 202 instead). Two ways to handle it:

1. Embed the contact in the event (recommended). Send the event with _user_data and skip the separate contacts call: the event creates or updates the contact itself. See embedding the contact in the event.
2. Retry the rejected event after a short wait, for example after 1, 2 and 4 seconds. The rejected event was not stored, so resending it with the same _event_id cannot create a duplicate.

Automations and the event time window

Every event you send is stored on the contact's timeline regardless of its date, but only events whose _event_date is close to reception time trigger automations. The Ingest API applies a symmetric window of ±1 hour around the moment we receive the request:

abs(_event_date − reception_time) ≤ 1 hour

Events outside that window are accepted, persisted and queryable for segmentation — they just do not fire any automation. This is a safeguard: without it, a single backfill of historical orders, a producer with clock drift, or a queue replayed after a long stall could enqueue thousands of SMS, emails and other messages for things that already happened.

In practice:

• Omit _event_date when the event is happening "now" — it defaults to the current time and is guaranteed to be inside the window.
• Send _event_date only when you genuinely need a specific timestamp, and make sure it is within ±1h of reception.
• Backfills of historical events for segmentation or analytics should be sent with their real dates. Automations will not fire for them — by design.

What to read next