Quickstart

This walkthrough exercises the three things every Product API integration eventually does: locate a contact, inspect their timeline, and trigger a direct message. Budget five minutes.

Before you start

1. 1

   Have a project with data

   Sign in to the dashboard and pick a project that already has at least one audience contact (either pushed via Ingest or imported via a data source). If your project is empty, walk through the Ingest Quickstart first.

2. 2

   Create a Product API token

   Open Project settings → API tokens and create a token with at least these scopes:

   • PROJECT_AUDIENCE_READ
   • PROJECT_AUDIENCE_DATA_BASIC (to see phone and email on responses)
   • PROJECT_AUDIENCE_DATA_EVENTS (to read events)
   • PROJECT_DIRECT_WRITE (to send direct SMS)
3. 3

   Export credentials

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

1. Verify the token

GET /v1/project/{project} returns the project's metadata and is the cheapest probe for credentials.

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

A 200 confirms the token is live and the project UID resolves. A 401 means the token is wrong; a 404 means the project UID is wrong or not visible to the token.

2. Find an audience contact

The audience exposes three search helpers for the common identifier types — user id, phone and email. They return the unified audience contact so you can then read events or send messages.

curl "$BASE/audience/search/phone/%2B34600000000" \
  -H "Authorization: Bearer $INSTASENT_TOKEN"

Response (trimmed):

{
  "entity": {
    "id": "uQTuHNBKLdwTxzGldW5pocUNqzyz-066",
    "_user_id": "USER-123",
    "_first_name": "Ada",
    "_email": "ada@example.com",
    "_phone_mobile": "+34600000000"
  }
}

Copy the returned id — that is the audience contact id you need for the next two calls.

export AUDIENCE_ID="uQTuHNBKLdwTxzGldW5pocUNqzyz-066"

3. Read the contact's recent events

curl "$BASE/audience/$AUDIENCE_ID/events" \
  -H "Authorization: Bearer $INSTASENT_TOKEN"

You get the last events for that contact — purchases, message deliveries, clicks, custom events. Use this to confirm your Ingest pipeline is landing and to drive application logic that depends on the customer timeline.

4. Send a direct SMS

The direct SMS endpoint takes the sender and audience id in the path and the text in the body. Use "default" as the sender id to fall back to the project's default sender.

curl -X POST "$BASE/channel/sms/sms/direct/default/$AUDIENCE_ID" \
  -H "Authorization: Bearer $INSTASENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hi Ada — your order is on its way. Track it at {{short:https://track.example.com/O-987}}"
  }'

A 201 Created returns the SMS entity with its id, status (enqueued initially), encoding, messagesCount, pricePerSms and the audienceId the message was dispatched to. Status transitions are pushed to your DLR webhook the same way transactional traffic is — see Transactional DLRs.

5. (Optional) send by phone instead of audience id

If the contact does not yet exist and your project has outbound auto-creation enabled, you can send straight to a phone number and let the API create the audience contact for you:

curl -X POST "$BASE/channel/sms/sms/direct/default/%2B34600000000" \
  -H "Authorization: Bearer $INSTASENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Welcome to Example Co." }'

The response's metadata.autoCreated is true when a new audience contact was created for the message. If auto-creation is disabled and the phone number is not found, the call returns 404.

What to read next