# Guide

The Product API is Instasent's primary management API: organizations, projects, data sources, unified audiences, events, segments, campaigns, automations and direct messaging, all under one token.

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, reads **segments**, **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 [Transactional API](/transactional-api/overview). If you only need to push customer data into a project, the [Ingest API](/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 and retrieve contacts from the audience that results from merging every data source in the project.
- **Events** — search and analyse audience events to understand customer behaviour.
- **Segments** — list static and dynamic segments and scroll their contacts.
- **Campaigns & automations** — read campaign and automation details, configurations and status.
- **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](/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 that project.

- **Primary merging attribute**: `_user_id`. Contacts across data sources with the same `_user_id` become a single audience contact.
- **Additional merging attributes**: a project can configure extras (typically `_email`, `_phone_mobile`). Any matching value triggers a merge.
- **Attribute consolidation**: when multiple data sources disagree about the same attribute, the project's priority rules pick the winner. The [Ingest API](/ingest-api/guide) datasource takes precedence by default.
- **Event aggregation**: every event from the merged contacts hangs off the unified audience contact, so you see one timeline per customer regardless of the source.
- **Source tracking**: the audience contact keeps references to every datasource contact it was built from, via the `_datasources` and `_ds_contact_ids` attributes. That lets you trace any value back to its origin.

For example: a contact with `_user_id: "12345"` that exists in both your CRM and your e-commerce data sources becomes a single audience contact whose attributes combine both and whose event timeline merges both histories.

## 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](/product-api/reference) for response shapes.

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

### Campaigns & automations

- `PROJECT_CAMPAIGN_READ` — read access to campaigns.
- `PROJECT_AUTOMATION_READ` — read access to automations.

### 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_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](/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](/product-api/quickstart) - Find a contact, read their events, send a direct SMS.
- [Authentication](/product-api/authentication) - Token types, scopes and rotation.
- [Audience query filter](/product-api/audience-query-filter) - Search and segment the unified audience.
- [API Reference](/product-api/reference) - Every endpoint, every parameter.