# Product API guide

The Product API is the CDP API — Instasent's Customer Data Platform: the unified audience with its events and segments, plus the organizations, projects, data sources, campaigns, automations and direct messaging around it, all under one token.

**Language:** en
**Audience:** developer
**TLDR:** The Product API is the CDP API — Instasent's Customer Data Platform, and its control plane: manage organizations and projects, merge contacts across data sources into one unified audience, save audience filters as segments, and read campaigns, automations and events, or send direct SMS. Call it with a Product API token and project UID from Project settings; use the A2P Messaging API for raw message throughput, or the Ingest API (a focused subset) to only push customer data.
**Docs index (every page):** https://docs.instasent.com/llms.txt
**This zone's index:** https://docs.instasent.com/developers/product-api/llms-full.txt
**This page:** https://docs.instasent.com/developers/product-api/guide/ (HTML) · https://docs.instasent.com/developers/product-api/guide.md (Markdown)

The Product API is the control plane for everything a brand runs on Instasent. It manages the **organization** and its **projects**, feeds contacts and events into **data sources**, queries the **unified audience** that results from merging those sources, keeps any of those queries as a named **segment**, reads **campaigns** and **automations**, and sends **direct SMS** to specific contacts when your application needs to trigger a message outside a campaign.

If you are looking for raw message throughput — OTPs, receipts, transactional SMS — see the [A2P Messaging API](/developers/transactional-api/overview). If you only need to push customer data into a project, the [Ingest API](/developers/ingest-api/guide) is a focused subset of this one with its own tokens.

> **Note**: You need a **Product API token** and your **project UID** to call these endpoints. Both live under **Project settings** in the [dashboard](https://dashboard.instasent.com).

## What you can do

The Product API gives you, under a single token:

- **Organizations & projects** — read organization info, open projects and manage project-level settings.
- **Data sources** — create and manage API data sources as entry points for customer data.
- **Unified audience** — query, search, count and analyse the contacts that result from merging every data source in the project. The whole surface has its own section: [Audience](/developers/product-api/audience/overview).
- **[Events](/developers/product-api/audience/events)** — search and analyse audience events to understand customer behaviour.
- **Segments** — list static and dynamic segments, scroll their contacts, and [save an audience filter](/developers/product-api/audience/segments) as a named segment the project keeps.
- **Campaigns, automations & flows** — read campaign, automation and flow details, configurations and status, including a flow's versions, and [create campaign drafts](/developers/product-api/campaigns/overview) for a human to review and send.
- **Direct messaging** — send direct SMS to specific audience contacts and manage SMS senders.
- **Ingest (built-in)** — push contacts and events into data sources using the same endpoints the [Ingest API](/developers/ingest-api/guide) exposes.

## Core entities

Five nouns keep reappearing in every endpoint. Getting them right up front saves pain later.

- **Organization** — the company on Instasent. Owns billing, user accounts, API tokens and a set of projects.
- **Project** — an isolated environment inside an organization. Holds its own data sources, audience, segments, campaigns and automations. Used to split brands, markets or customer segments.
- **Data source** — a stream of contacts and events that feeds into a project. A project can have many. Each has its own contacts and events; merging happens at the audience level.
- **Contact** — a person. Exists in two forms:
  - **Datasource contact** — the original record as it arrived in a specific data source.
  - **Audience contact** (also called the *unified audience*) — the merged view across every data source in the project.
- **Event** — an immutable record of a customer interaction (purchase, view, opt-in, any custom activity). Events enrich contact profiles and can trigger automations.

## How contacts merge into the unified audience

The unified audience is the product of merging every data source in the project by the **merging attributes** configured on it. `_user_id` is the primary one, a project usually configures extras such as `_email` and `_phone_mobile`, and a match on any of them merges the records into a single audience contact whose event timelines join.

So a contact with `_user_id: "12345"` present in both your CRM and your e-commerce data sources becomes one audience contact, combining both sets of attributes and both histories. When two sources disagree about a value, the project's priority rules pick the winner.

The full model, including what a `datasource` narrowing does and does not mean, is on [Contacts and attributes](/developers/product-api/audience/contacts-and-attributes) in the [Audience](/developers/product-api/audience/overview) section.

## Discovering what's in a project

The attributes a contact can carry and the event types you can filter on are **project-specific** — they depend on how the project is configured and which datasources feed it. Rather than maintain a static catalogue here, the API exposes three discovery endpoints that always return the live shape of your project:

- `GET /v1/project/{project}/specs/attributes` — every attribute enabled on contacts in this project: its `uid`, `dataType`, whether it is `unique` (used for merging), `custom`, `readonly`, `eventBased`, etc.
- `GET /v1/project/{project}/specs/events` — every event type available in this project, including category, attribution and automation flags.
- `GET /v1/project/{project}/specs/events/{eventType}` — the parameter schema for a specific event type: `parameter` key, `dataType`, `required`, `maxLength`, `multiValue`.

Use these to validate payloads before writing, to build dynamic UIs on top of the audience, or just to discover which event types (`ecommerce_order_create`, `appointment`, custom ones…) and parameters are in play. See the [API Reference](/developers/product-api/reference) for response shapes.

Specs answer *what data shape can this project hold*. A second pair of endpoints answers the operational question *is this project ready to operate, and what's blocking it* — also computed live from the project's current configuration:

- `GET /v1/project/{project}/readiness` — the live setup-readiness report for the project: the steps still left to configure and the warnings that need attention, with a percent-complete figure and an operational flag telling you whether the project can send at all.
- `GET /v1/project/{project}/readiness/channel/{channel}` — the same report scoped to one channel (`channel` ∈ `sms` | `rcs`): channel-specific setup steps (add a sender for `sms`, add an agent for `rcs`), warnings surfacing senders or registers that need review, and a `reach` object listing the countries you can send to right now on this channel — a union plus a per-sender breakdown (the positive counterpart of `warnings`). `reach` is `null` on the project (home) scope.

Use these to drive an onboarding checklist or a "your project isn't ready yet" banner, or to gate sending in your own tooling. See the [API Reference](/developers/product-api/reference) for the full report shape.

Specs answer what the project *can* hold; a third pair answers what it *actually* holds. `POST /audience/coverage` and `POST /event/volumes` are **probes**: they measure the audience attribute by attribute and event type by event type, so you know an attribute is filled and a value occurs before you build a filter on it. See [Audience probes](/developers/product-api/audience/probes). They report shape, never size: for a size, `/audience/count`.

## Tokens and scopes

Access is controlled by **token scopes**. A token is minted for an organization or project and carries only the scopes you grant it — a read-only reporting token looks nothing like the write token behind your CRM sync.

### Datasource management

- `PROJECT_DATASOURCE_READ` — read-only access to data sources.
- `PROJECT_DATASOURCE_WRITE` — create and modify data sources.

### Organization

- `ACCOUNT_READ` — read organization account details, including funds.

### Audience

- `PROJECT_AUDIENCE_READ` — read individual audience contacts, and read segments (list, view, usage).
- `PROJECT_AUDIENCE_WRITE` — write to audience contacts.
- `PROJECT_AUDIENCE_LIST` — list audience contacts (scroll/search). *Requires a specific subscription plan.*
- `PROJECT_AUDIENCE_DATA_BASIC` — access to basic contact data. *Requires a specific subscription plan.*
- `PROJECT_AUDIENCE_DATA_FULL` — access to full contact data (PII). *Must be manually granted by Instasent.*
- `PROJECT_AUDIENCE_DATA_EVENTS` — access to audience events. *Requires a specific subscription plan.*
- `PROJECT_AGGREGATIONS` — audience and event aggregations. *Must be manually granted by Instasent.*

### Segments

- `PROJECT_SEGMENT_WRITE` — [save an audience filter as a segment](/developers/product-api/audience/segments). A scope of its own, so a token can be allowed to keep segments without being given write access to the audience. Reading segments back needs `PROJECT_AUDIENCE_READ`, not this one.

### Campaigns, automations & flows

- `PROJECT_CAMPAIGN_READ` — read access to campaigns. Required by [reading campaigns](/developers/product-api/campaigns/reading-campaigns), including the project digest.
- `PROJECT_CAMPAIGN_WRITE` — create campaign drafts. Required by [campaign creation](/developers/product-api/campaigns/creating-a-draft), and by [estimating and deleting](/developers/product-api/campaigns/estimating-and-deleting); it does not allow sending, which stays in the dashboard.
- `PROJECT_AUTOMATION_READ` — read access to automations, and to flows and their versions.

### Direct messaging

- `PROJECT_DIRECT_READ` — read direct SMS.
- `PROJECT_DIRECT_WRITE` — create direct SMS. Required to send.

### Data privacy and plan gating

The contact fields a call returns depend on **two** things: the scopes on your token **and** the subscription plan of the organization. Having the scope in the token spec is not enough — the plan has to allow it.

| Level       | Required scope                | Returned fields                                 |
| ----------- | ----------------------------- | ----------------------------------------------- |
| **Default** | `PROJECT_AUDIENCE_READ`       | Full name and user id only.                     |
| **Basic**   | `PROJECT_AUDIENCE_DATA_BASIC` | Phone, email, country, name and boolean fields. |
| **Full**    | `PROJECT_AUDIENCE_DATA_FULL`  | Full contact data including PII.                |

Scopes fall into three availability tiers:

- **Always available**: `PROJECT_AUDIENCE_READ`, `PROJECT_AUDIENCE_WRITE`, `PROJECT_DATASOURCE_READ/WRITE`, `PROJECT_SEGMENT_WRITE`, `PROJECT_CAMPAIGN_READ`, `PROJECT_AUTOMATION_READ`, `PROJECT_DIRECT_READ/WRITE`, `ACCOUNT_READ`.
- **Gated by subscription plan**: `PROJECT_AUDIENCE_LIST`, `PROJECT_AUDIENCE_DATA_BASIC`, `PROJECT_AUDIENCE_DATA_EVENTS`. These are grantable only on plans that include them — upgrade the plan from the [dashboard](https://dashboard.instasent.com) if you need them.
- **Manually granted by Instasent**: `PROJECT_AUDIENCE_DATA_FULL`, `PROJECT_AGGREGATIONS`. Not generally available, reserved for trusted partners, require approval.

> **Warning**: Design your integration against **Basic** access. If your plan does not include `PROJECT_AUDIENCE_DATA_BASIC`, most contact fields come back redacted to Default level regardless of what your code expects. Upgrade the plan before assuming the data is there.

### Datasource-specific tokens

Every data source can also mint its own token. Those tokens are write-only, scoped to the single data source, and are the recommended path for CRM or e-commerce syncs — see [Ingest API authentication](/developers/ingest-api/authentication).

## Multi-project architecture

Projects are fully isolated. Each one keeps its own:

- data sources and contacts,
- unified audience and events,
- segments, campaigns and automations,
- SMS senders and direct messages.

Use that isolation to split brands, markets or product lines without cross-contaminating audiences. A single organization can run many projects side by side.

## What to read next

- [Quickstart](/developers/product-api/quickstart) - Find a contact, read their events, send a direct SMS.
- [Authentication](/developers/product-api/authentication) - Token types, scopes and rotation.
- [Audience](/developers/product-api/audience/overview) - The whole audience surface: contacts, events, filters, probes, counting and segments.
- [Campaigns](/developers/product-api/campaigns/overview) - Draft campaigns, read them back, price them and delete them.
- [Full API Reference](/developers/product-api/reference) - Every endpoint, every parameter.

---

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.