Sign in

a84d4905fdbb

latestOpenAPI 3.1.02026-08-143874115.7 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.

Example request

{
  "account_id": "biz_xxxxxxxxxxxxxx",
  "audience_type": "lookalike",
  "auto_refresh": true,
  "column_mapping": {
    "country": "Country",
    "email": "Email",
    "first_name": "First Name",
    "last_name": "Last Name",
    "ltv": "Lifetime Value",
    "phone": "Phone"
  },
  "count": 3,
  "file_id": "eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "filters": {
    "country": "US",
    "last_seen_within_days": 30
  },
  "name": "Austin visitors, last 30 days",
  "percentage": 6,
  "source_audience_id": "adaud_xxxxxxxxxxxxxx"
}

Response

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

OR

Example response

{
  "audience_type": "lookalike",
  "created_at": "2026-01-01T12:00:00.000Z",
  "error_message": "412 of 1,000 rows had no email or phone number, so the list could not be matched.",
  "filters": {
    "country": "US",
    "last_seen_within_days": 30
  },
  "id": "adaud_xxxxxxxxxxxxxx",
  "last_refreshed_at": "2026-01-01T12:00:00.000Z",
  "lookalike_ratio": 0.04,
  "lookalike_starting_ratio": 0.02,
  "match_rates": [
    {
      "lower_bound": 40,
      "platform": "meta",
      "status": "available",
      "upper_bound": 50
    }
  ],
  "name": "Past purchasers Lookalike 2–4%",
  "platform_audience_ids": [
    "120246230799130687"
  ],
  "source_audience_id": "adaud_xxxxxxxxxxxxxx",
  "source_type": "csv_upload",
  "updated_at": "2026-01-01T12:00:00.000Z"
}