Audience

Instasent is a customer data platform, and the audience is the thing it is a platform for. Everything else in the Product API either feeds the audience, asks it a question, or acts on the answer. A project holds exactly one audience: not a set of lists you maintain in parallel, but a single merged view of every person the project knows, assembled from every data source that ever sent that project data.

This section is the working guide to that audience over the API: what it is made of, how to ask it questions, how to check that the answer means what you think it means, and how to keep a question you want to reuse.

The model

flowchart TD
    DS1[Data source: CRM]
    DS2[Data source: e-commerce]
    DS3[Data source: Ingest API]
    DSC[Datasource contacts<br/>one record per source]
    AUD[Audience contact<br/>one consolidated record per person]
    EV[Events<br/>what the person did]
    QF[Query filter<br/>selects contacts]
    SEG[Segment<br/>a saved filter]
    CMP[Campaigns and automations]

    DS1 --> DSC
    DS2 --> DSC
    DS3 --> DSC
    DSC -->|merged by the project's merging attributes| AUD
    EV -->|attached to the person| AUD
    AUD --> QF
    QF -->|saved with a name| SEG
    QF --> CMP
    SEG --> CMP

Five nouns carry the whole section:

Data source is a stream of contacts and events feeding one project. A project can have many, and each keeps its own original records.
Datasource contact is the record exactly as it arrived in one source.
Audience contact is the consolidated projection of every datasource contact that turned out to be the same person. This is what you query, count and message. It is not a copy of one source's record: it is the merged result, and no single field on it is guaranteed to have come from any particular source.
Event is an immutable record of something the person did. Events hang off the audience contact, so one person has one timeline no matter how many sources reported parts of it.
Segment is a saved filter, not a stored list. It holds a question, and the answer is recomputed when it is used.

What lives in this section

Contacts and attributes

How records from several sources become one contact, and what system and custom attributes it carries.

Events

The event model: types, parameters, the project's catalogue, and what actually arrives.

Query filter

The grammar that selects contacts: attribute, event and segment conditions.

Event query filter

The grammar that selects events directly, with its own aggregation surface.

Probes

Measure what the audience actually contains before you filter it. Probe first, then filter.

Counting and retrieval

Count, search, scroll: which endpoint answers which question, and what each returns.

Segments

Keep a filter as a named segment, read it back, audit where it is used.

How big is my audience

Before composing anything, the cheapest question has its own endpoint. GET /project/{project}/audience/overview returns the project's total contacts and, for every channel the project can send on, how many of them are actually reachable under the project's own consent policy, together with what each other policy would reach.

GET/project/{project}/audience/overview

Total contacts plus reachable contacts per channel, and the full policy ladder.

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

Two things about the answer. It carries aggregate numbers only, with no contact rows, so it is not restricted by the project's data policy and needs nothing beyond PROJECT_AUDIENCE_READ. And its counters are cached, with an age reported in computedAgo that you should narrate along with the figure rather than presenting it as a live total. Channels the project cannot send on simply do not appear.

Use it when the question is "what is my audience" or "what would I gain by asking for opt-in". Use /audience/count when the question is about a specific filter.

Three rules worth knowing before you start

The contact is a projection, not a record

An audience contact is built from every source that touched that person, and the project's priority rules pick the winner when two sources disagree about the same attribute. So "this contact came from the CRM" is not a meaningful statement about a value: the contact came from all of them. Narrowing anything by datasource selects contacts a source contributed to, never the values it supplied. The consequences are worked through in Contacts and attributes.

Who the contacts are and who may be messaged are separate questions, resolved at different moments. A filter and a segment answer the first. Reach under a channel's consent policy is resolved when something is sent, and it is available on demand through the filterCompliance key of a count. Never bake consent into a saved segment.

Probe before you filter

A condition on an attribute almost nobody filled, or on a value spelled differently in the data, is a perfectly valid filter that selects nobody. It returns 200. Nothing errors. The two probes exist to close that gap, and reaching for them costs one request.

Scopes

The whole section runs on the audience scopes described in the Product API guide. In short:

You want to	Scope
Read a contact, read segments, count, probe	`PROJECT_AUDIENCE_READ`
Scroll contacts, or scroll a segment	`PROJECT_AUDIENCE_LIST` (plan-gated)
See phone, email, country and names on returned contacts	`PROJECT_AUDIENCE_DATA_BASIC` (plan-gated)
Read events on a contact	`PROJECT_AUDIENCE_DATA_EVENTS` (plan-gated)
Save a filter as a segment	`PROJECT_SEGMENT_WRITE`
Run your own aggregations	`PROJECT_AGGREGATIONS` (granted by Instasent)

What's next

Contacts and attributes: the merge model and the attribute catalogue, which is where most integration surprises come from.
Query filter: the grammar, once you know what you are filtering on.
Full API Reference: every audience, event and segment endpoint.