Sign in

v8

OpenAPI 3.1.02026-08-033623795.0 MB
Audiences

Create Audience

Creates an audience. Default (audience_type omitted or custom): creates one audience from an uploaded customer identity CSV file (name, column_mapping, and file_id required) and starts processing it; responds with the audience object. With filters: creates an audience from saved People filters (name required) — membership is built from the account's People data, and auto_refresh decides whether it keeps tracking the filters or keeps whoever matched at creation. With audience_type: lookalike: creates a ladder of Meta lookalike audiences from an existing ready custom audience (source_audience_id, count, and percentage required) — count equal similarity bands slicing the top percentage% (3 audiences at 6% = 0–2%, 2–4%, 4–6%), each returned as its own audience in a { data: [...] } envelope.

post/audiences

Headers

Idempotency-Keystring
Example:d9105228-4a08-46b1-8b91-42fed586d383

A unique key that makes this request safe to retry. See Idempotent requests.

Request body

account_idstring required

Account ID, prefixed biz_.

audience_type'custom' | 'lookalike'

What to create. Defaults to custom (CSV upload).

auto_refreshboolean

Filter audiences only, and set only at creation. true (the default) rebuilds membership from the filters twice a day. false keeps whoever matched at creation and never rebuilds.

countinteger

Lookalikes only. Number of lookalike audiences to create (1–6).

file_idstring

Custom audiences only. The uploaded customer CSV — a file id (file_...) returned by POST /files.

filtersobject

Filter audiences only. The People filters that define membership, keyed exactly as GET /people accepts them — for example {"os": "iOS", "country": "US"}. Date filters must be rolling windows — first_seen_within_days or last_seen_within_days — so the audience re-anchors on every refresh; fixed dates such as first_seen_after are rejected. Source values are canonical source paths (whop:<campaign>:<group>:<ad>, ext:<platform>:..., referrer:<domain>, direct), exact or with a trailing :* wildcard.

namestring

Audience display name. Required for custom audiences; lookalike names are generated from the source audience.

percentageinteger

Lookalikes only. Total similarity reach as a whole percent (1–20), sliced evenly across count — must be divisible by count.

source_audience_idstring

Lookalikes only. The ready custom audience (adaud_) to build from; it needs at least 100 matched people.

Response

Audience created — the audience object for custom audiences, or { data: [...] } for lookalike ladders.

OR

Example response

{
  "audience_type": "custom",
  "match_rates": [
    {
      "platform": "meta",
      "status": "calculating"
    }
  ],
  "source_type": "csv_upload"
}