Product API guide

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. If you only need to push customer data into a project, the Ingest API is a focused subset of this one with its own tokens.

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.
• Events — search and analyse audience events to understand customer behaviour.
• Segments — list static and dynamic segments, scroll their contacts, and save an audience filter 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 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 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 in the Audience 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 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 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. 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. 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, including the project digest.
• PROJECT_CAMPAIGN_WRITE — create campaign drafts. Required by campaign creation, and by 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 if you need them.
• Manually granted by Instasent: PROJECT_AUDIENCE_DATA_FULL, PROJECT_AGGREGATIONS. Not generally available, reserved for trusted partners, require approval.

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.

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