Quickstart

This walkthrough ends with one contact in your datasource and one event on their timeline. Budget five minutes.

Before you start

1. 1

   Have a project

   Sign in to the dashboard and pick the project that will receive the data. If this is your first time, create a throw-away project — it makes cleanup trivial once you have finished exploring.

2. 2

   Create a datasource

   Inside the project, open Datasources → New datasource → API. Copy the project, datasource and the generated token — you will not see the token again.

3. 3

   Export them as env vars

   export INSTASENT_PROJECT="proj_xxx"
   export INSTASENT_DATASOURCE="ds_xxx"
   export INSTASENT_TOKEN="eyJhbGciOi..."
   export BASE="https://api.instasent.com/v1/project/$INSTASENT_PROJECT/datasource/$INSTASENT_DATASOURCE"

1. Verify the token

GET /stream returns metadata and is the cheapest way to confirm your credentials work.

curl "$BASE/stream" \
  -H "Authorization: Bearer $INSTASENT_TOKEN"

You should get a 200 with an object describing the organization, project, datasource and recent usage. A 401 means the token is wrong; a 404 means the project or datasource id is wrong.

2. Create a contact

POST /stream/contacts takes an array even when you only have one record. The reserved _-prefixed fields are Instasent's known attributes; everything else becomes a custom attribute on the contact.

curl -X POST "$BASE/stream/contacts" \
  -H "Authorization: Bearer $INSTASENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "_user_id": "USER-123",
      "_first_name": "Ada",
      "_last_name": "Lovelace",
      "_email": "ada@example.com",
      "_phone_mobile": "+34600000000",
      "plan": "pro",
      "signup_source": "landing-a"
    }
  ]'

A 202 Accepted with a per-item outcome means the contact is in flight to the audience; it will be queryable within seconds. Partial failures come back in the same body — see Errors.

3. Record an event

Events must carry a stable _event_id so retries are idempotent. Pick one from your source system (order id, message id, click id…) and reuse it if you ever resend.

curl -X POST "$BASE/stream/events" \
  -H "Authorization: Bearer $INSTASENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "_user_id": "USER-123",
      "_event_id": "ORDER-987",
      "_event_type": "purchase",
      "_event_parameters": {
        "currency": "EUR",
        "amount": 49.90,
        "product_sku": "SKU-42"
      }
    }
  ]'

202 Accepted again. The event lands on the contact's timeline and becomes queryable for segmentation.

4. (Optional) embed the contact in the event

If your source system produces the event and the contact at the same time, you can skip the separate contacts call:

{
  "_user_id": "USER-456",
  "_event_id": "ORDER-988",
  "_event_type": "purchase",
  "_user_data": {
    "_email": "grace@example.com",
    "_first_name": "Grace"
  },
  "_event_parameters": {
    "currency": "EUR",
    "amount": 12.50
  }
}

The contact is upserted before the event is processed. If the upsert fails, the event is skipped.

5. Delete the contact (cleanup)

When you are ready to tear down your test run:

curl -X DELETE "$BASE/stream/contacts/USER-123" \
  -H "Authorization: Bearer $INSTASENT_TOKEN"

The contact is permanently removed from the audience.

What to read next