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, 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. 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 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 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 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 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 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