---
title: "Create Audience"
method: POST
path: "/audiences"
tags: ["Audiences"]
---

# Create Audience

`POST /audiences`

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.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `account_id` string, required — Account ID, prefixed `biz_`.
  - `audience_type` 'custom' | 'lookalike' — What to create. Defaults to `custom` (CSV upload).
  - `auto_refresh` boolean — 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.
  - `column_mapping` object — Custom audiences only. Maps supported identity fields to CSV column headers. Map at least one of `email` or `phone`.
    - `country` string — CSV header for ISO 3166-1 alpha-2 country codes, such as `US`.
    - `email` string — CSV header for email addresses.
    - `first_name` string — CSV header for first names.
    - `last_name` string — CSV header for last names.
    - `ltv` string — CSV header for each customer's lifetime value — a non-negative number, currency symbols allowed. When mapped, Meta creates the audience as value-based, so lookalikes built from it favor people similar to the highest-value customers.
    - `phone` string — CSV header for phone numbers.
  - `count` integer — Lookalikes only. Number of lookalike audiences to create (1–6).
  - `file_id` string — Custom audiences only. The uploaded customer CSV — a file id (`file_...`) returned by `POST /files`.
  - `filters` object — 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.
  - `name` string — Audience display name. Required for custom audiences; lookalike names are generated from the source audience.
  - `percentage` integer — Lookalikes only. Total similarity reach as a whole percent (1–20), sliced evenly across `count` — must be divisible by `count`.
  - `source_audience_id` string — Lookalikes only. The ready custom audience (`adaud_`) to build from; it needs at least 100 matched people.

## Response `201`

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

- union
  - Audience
    - `audience_type` 'custom' | 'lookalike', required — `custom` = a customer list (uploaded, or built from saved People filters); `lookalike` = Meta lookalike built from a custom audience.
    - `auto_refresh` boolean, required — Whether membership keeps updating. `true` rebuilds it from the saved filters twice a day, so people join and leave as they start and stop matching. `false` keeps whoever matched when it was built and never rebuilds. Always `false` for uploaded lists and lookalikes.
    - `created_at` string, required — When the audience was created, as an ISO 8601 timestamp.
    - `error_message` string, nullable, required — Processing error message. `null` unless processing is partial or failed.
    - `filters` object, nullable, required — For audiences built from People filters: the filters that define membership, keyed exactly as `GET /people` accepts them — for example `{"os": "iOS", "country": "US"}`. `null` for uploaded lists and lookalikes.
    - `id` string, required — Audience ID, prefixed `adaud_`.
    - `last_refreshed_at` string, nullable, required — When the audience membership was last rebuilt, as an ISO 8601 timestamp. `null` until the first build completes.
    - `lookalike_ratio` number, nullable, required — For lookalikes: the upper bound of the similarity band as a fraction (0.02 = top 2%). `null` for custom audiences.
    - `lookalike_starting_ratio` number, nullable, required — For lookalikes: the lower bound of the similarity band as a fraction. `null` for custom audiences and first-tier lookalikes.
    - `match_rates` AudienceMatchRate[], required
      - `lower_bound` number, nullable, required — Lower bound of the estimated match rate percentage. `null` until available.
      - `platform` 'meta', required — The ad platform that provided the match-rate estimate.
      - `status` 'calculating' | 'available' | 'unavailable' | 'null', nullable, required — Availability of the estimated match rate.
      - `upper_bound` number, nullable, required — Upper bound of the estimated match rate percentage. `null` until available.
    - `matched_rows` number, required — Members successfully uploaded to connected ad accounts. Always 0 for lookalikes.
    - `name` string, required — Audience display name.
    - `platform_audience_ids` string[], required
    - `processed_rows` number, required — Members processed from the source so far. Always 0 for lookalikes.
    - `progress_percent` number, required — Processing progress from 0 to 100.
    - `source_audience_id` string, nullable, required — For lookalikes: the audience this lookalike was built from. `null` for custom audiences.
    - `source_type` 'csv_upload' | 'people_filter', required — Where members come from. `csv_upload` = an uploaded customer list; `people_filter` = built from saved People filters. See `auto_refresh` for whether a `people_filter` audience keeps updating.
    - `status` 'pending' | 'processing' | 'syncing' | 'ready' | 'partial' | 'failed', required — Current state of the audience import. `syncing` means Whop is sending matched rows to connected ad accounts. When status is `partial` or `failed`, `error_message` explains what went wrong.
    - `total_rows` number, required — Total members detected in the source — CSV rows for uploaded lists, matching people for automatic audiences. Always 0 for lookalikes.
    - `updated_at` string, required — When the audience was last updated, as an ISO 8601 timestamp.
  - object
    - `data` Audience[], required
      - `audience_type` 'custom' | 'lookalike', required — `custom` = a customer list (uploaded, or built from saved People filters); `lookalike` = Meta lookalike built from a custom audience.
      - `auto_refresh` boolean, required — Whether membership keeps updating. `true` rebuilds it from the saved filters twice a day, so people join and leave as they start and stop matching. `false` keeps whoever matched when it was built and never rebuilds. Always `false` for uploaded lists and lookalikes.
      - `created_at` string, required — When the audience was created, as an ISO 8601 timestamp.
      - `error_message` string, nullable, required — Processing error message. `null` unless processing is partial or failed.
      - `filters` object, nullable, required — For audiences built from People filters: the filters that define membership, keyed exactly as `GET /people` accepts them — for example `{"os": "iOS", "country": "US"}`. `null` for uploaded lists and lookalikes.
      - `id` string, required — Audience ID, prefixed `adaud_`.
      - `last_refreshed_at` string, nullable, required — When the audience membership was last rebuilt, as an ISO 8601 timestamp. `null` until the first build completes.
      - `lookalike_ratio` number, nullable, required — For lookalikes: the upper bound of the similarity band as a fraction (0.02 = top 2%). `null` for custom audiences.
      - `lookalike_starting_ratio` number, nullable, required — For lookalikes: the lower bound of the similarity band as a fraction. `null` for custom audiences and first-tier lookalikes.
      - `match_rates` AudienceMatchRate[], required
        - `lower_bound` number, nullable, required — Lower bound of the estimated match rate percentage. `null` until available.
        - `platform` 'meta', required — The ad platform that provided the match-rate estimate.
        - `status` 'calculating' | 'available' | 'unavailable' | 'null', nullable, required — Availability of the estimated match rate.
        - `upper_bound` number, nullable, required — Upper bound of the estimated match rate percentage. `null` until available.
      - `matched_rows` number, required — Members successfully uploaded to connected ad accounts. Always 0 for lookalikes.
      - `name` string, required — Audience display name.
      - `platform_audience_ids` string[], required
      - `processed_rows` number, required — Members processed from the source so far. Always 0 for lookalikes.
      - `progress_percent` number, required — Processing progress from 0 to 100.
      - `source_audience_id` string, nullable, required — For lookalikes: the audience this lookalike was built from. `null` for custom audiences.
      - `source_type` 'csv_upload' | 'people_filter', required — Where members come from. `csv_upload` = an uploaded customer list; `people_filter` = built from saved People filters. See `auto_refresh` for whether a `people_filter` audience keeps updating.
      - `status` 'pending' | 'processing' | 'syncing' | 'ready' | 'partial' | 'failed', required — Current state of the audience import. `syncing` means Whop is sending matched rows to connected ad accounts. When status is `partial` or `failed`, `error_message` explains what went wrong.
      - `total_rows` number, required — Total members detected in the source — CSV rows for uploaded lists, matching people for automatic audiences. Always 0 for lookalikes.
      - `updated_at` string, required — When the audience was last updated, as an ISO 8601 timestamp.

## Other responses

- `401` — Unauthorized

---

[API](https://skmtc.net/whop/apis/whop-api.md) · [All operations](https://skmtc.net/whop/apis/whop-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/whop/whop-api/versions/866821546d67/schema)