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

# Create Audience

`POST /audiences`

Create an audience from a customer list, your account's Whop People data, or engagement with videos, lead forms, Instagram profiles, or Facebook pages. Create lookalike audiences to reach people similar to an existing audience. Processing runs asynchronously. Custom creation returns one audience; lookalike creation returns the requested similarity bands in `data`.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `account_id` string, required — Account ID, prefixed `biz_`.
  - `audience_type` 'custom' | 'lookalike' — Audience type. Defaults to `custom`.
  - `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 — CSV 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).
  - `engagement` object — Rules for membership based on social engagement. Requires a connected social account with advertising access.
    - `exclude` AudienceEngagementRule[] — Exclude anyone matching any exclusion rule. Defaults to an empty array. Video audiences do not support exclusions; use a separate audience in ad-group exclusions.
      - union
        - AudienceEngagementVideoRule
          - `event` 'watched_3_seconds' | 'watched_10_seconds' | 'watched_15_seconds' | 'watched_25_percent' | 'watched_50_percent' | 'watched_75_percent' | 'watched_95_percent', required — Interaction that qualifies a person for this rule.
          - `object` 'video', required — Engagement source.
          - `platform_video_ids` string[], required
          - `retention_days` integer, required — Rolling membership window in days, from 1 to 365.
          - `social_account_id` string, required — Connected social account ID, prefixed `sacc_`, with advertising access.
        - AudienceEngagementLeadFormRule
          - `event` 'opened' | 'submitted' | 'not_submitted', required — Interaction that qualifies a person for this rule.
          - `object` 'lead_form', required — Engagement source.
          - `platform_form_ids` string[], required
          - `retention_days` integer, required — Rolling membership window in days, from 1 to 90.
          - `social_account_id` string, required — Connected social account ID, prefixed `sacc_`, with advertising access.
        - AudienceEngagementInstagramProfileRule
          - `event` 'all' | 'engaged' | 'visited' | 'messaged' | 'saved' | 'ad_liked' | 'ad_commented' | 'ad_shared' | 'ad_saved' | 'ad_cta_clicked' | 'ad_carousel_swiped' | 'organic_liked' | 'organic_commented' | 'organic_shared' | 'organic_saved' | 'organic_swiped' | 'organic_carousel_swiped', required — Interaction that qualifies a person for this rule.
          - `object` 'instagram_profile', required — Engagement source.
          - `retention_days` integer, required — Rolling membership window in days, from 1 to 730.
          - `social_account_id` string, required — Connected social account ID, prefixed `sacc_`, with advertising access.
        - AudienceEngagementFacebookPageRule
          - `event` 'engaged' | 'visited' | 'liked' | 'messaged' | 'cta_clicked' | 'saved' | 'post_interaction', required — Interaction that qualifies a person for this rule.
          - `object` 'facebook_page', required — Engagement source.
          - `retention_days` integer, required — Rolling membership window in days, from 1 to 730. Use 0 for `liked`, which tracks current likes and cannot be combined with other events.
          - `social_account_id` string, required — Connected social account ID, prefixed `sacc_`, with advertising access.
    - `include` AudienceEngagementRule[], required — Match any inclusion rule. Video rules must share a retention window and cannot be combined with other sources.
      - union
        - AudienceEngagementVideoRule
          - `event` 'watched_3_seconds' | 'watched_10_seconds' | 'watched_15_seconds' | 'watched_25_percent' | 'watched_50_percent' | 'watched_75_percent' | 'watched_95_percent', required — Interaction that qualifies a person for this rule.
          - `object` 'video', required — Engagement source.
          - `platform_video_ids` string[], required
          - `retention_days` integer, required — Rolling membership window in days, from 1 to 365.
          - `social_account_id` string, required — Connected social account ID, prefixed `sacc_`, with advertising access.
        - AudienceEngagementLeadFormRule
          - `event` 'opened' | 'submitted' | 'not_submitted', required — Interaction that qualifies a person for this rule.
          - `object` 'lead_form', required — Engagement source.
          - `platform_form_ids` string[], required
          - `retention_days` integer, required — Rolling membership window in days, from 1 to 90.
          - `social_account_id` string, required — Connected social account ID, prefixed `sacc_`, with advertising access.
        - AudienceEngagementInstagramProfileRule
          - `event` 'all' | 'engaged' | 'visited' | 'messaged' | 'saved' | 'ad_liked' | 'ad_commented' | 'ad_shared' | 'ad_saved' | 'ad_cta_clicked' | 'ad_carousel_swiped' | 'organic_liked' | 'organic_commented' | 'organic_shared' | 'organic_saved' | 'organic_swiped' | 'organic_carousel_swiped', required — Interaction that qualifies a person for this rule.
          - `object` 'instagram_profile', required — Engagement source.
          - `retention_days` integer, required — Rolling membership window in days, from 1 to 730.
          - `social_account_id` string, required — Connected social account ID, prefixed `sacc_`, with advertising access.
        - AudienceEngagementFacebookPageRule
          - `event` 'engaged' | 'visited' | 'liked' | 'messaged' | 'cta_clicked' | 'saved' | 'post_interaction', required — Interaction that qualifies a person for this rule.
          - `object` 'facebook_page', required — Engagement source.
          - `retention_days` integer, required — Rolling membership window in days, from 1 to 730. Use 0 for `liked`, which tracks current likes and cannot be combined with other events.
          - `social_account_id` string, required — Connected social account ID, prefixed `sacc_`, with advertising access.
    - `platform` 'meta', required — Ad platform that maintains membership.
  - `file_id` string — CSV 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`. For example, 3 audiences at 6% creates 0–2%, 2–4%, and 4–6% bands.
  - `source_audience_id` string — Lookalikes only. The ready custom audience (`adaud_`) to build from; uploaded and People audiences need at least 100 matched people. Meta validates engagement audience eligibility when creating the lookalike.
  - `source_type` 'csv_upload' | 'people_filter' | 'engagement' — Custom audience source. Inferred from `engagement`, then `filters`, otherwise defaults to `csv_upload`. Supply only the fields for the selected source.

## Response `201`

Audience created. Custom creation returns one audience; lookalike creation returns an array in `data`.

- union
  - Audience
    - `audience_type` 'custom' | 'lookalike', required — Whether the audience targets a defined group of people or people similar to an existing audience.
    - `auto_refresh` boolean, required — Whether Whop rebuilds membership from saved People filters twice a day. When `false`, People audiences keep the members matched at creation. Always `false` for uploaded lists, lookalikes, and engagement audiences. Engagement membership is maintained by Meta.
    - `created_at` string, required — When the audience was created, as an ISO 8601 timestamp.
    - `engagement` AudienceEngagement, required
      - `exclude` AudienceEngagementRule[], required — Exclude anyone matching any exclusion rule. Supply 0–10 rules. Video audiences do not support exclusions; use a separate audience in ad-group exclusions.
        - union
          - AudienceEngagementVideoRule
            - `event` 'watched_3_seconds' | 'watched_10_seconds' | 'watched_15_seconds' | 'watched_25_percent' | 'watched_50_percent' | 'watched_75_percent' | 'watched_95_percent', required — Interaction that qualifies a person for this rule.
            - `object` 'video', required — Engagement source.
            - `platform_video_ids` string[], required
            - `retention_days` integer, required — Rolling membership window in days, from 1 to 365.
            - `social_account_id` string, required — Connected social account ID, prefixed `sacc_`, with advertising access.
          - AudienceEngagementLeadFormRule
            - `event` 'opened' | 'submitted' | 'not_submitted', required — Interaction that qualifies a person for this rule.
            - `object` 'lead_form', required — Engagement source.
            - `platform_form_ids` string[], required
            - `retention_days` integer, required — Rolling membership window in days, from 1 to 90.
            - `social_account_id` string, required — Connected social account ID, prefixed `sacc_`, with advertising access.
          - AudienceEngagementInstagramProfileRule
            - `event` 'all' | 'engaged' | 'visited' | 'messaged' | 'saved' | 'ad_liked' | 'ad_commented' | 'ad_shared' | 'ad_saved' | 'ad_cta_clicked' | 'ad_carousel_swiped' | 'organic_liked' | 'organic_commented' | 'organic_shared' | 'organic_saved' | 'organic_swiped' | 'organic_carousel_swiped', required — Interaction that qualifies a person for this rule.
            - `object` 'instagram_profile', required — Engagement source.
            - `retention_days` integer, required — Rolling membership window in days, from 1 to 730.
            - `social_account_id` string, required — Connected social account ID, prefixed `sacc_`, with advertising access.
          - AudienceEngagementFacebookPageRule
            - `event` 'engaged' | 'visited' | 'liked' | 'messaged' | 'cta_clicked' | 'saved' | 'post_interaction', required — Interaction that qualifies a person for this rule.
            - `object` 'facebook_page', required — Engagement source.
            - `retention_days` integer, required — Rolling membership window in days, from 1 to 730. Use 0 for `liked`, which tracks current likes and cannot be combined with other events.
            - `social_account_id` string, required — Connected social account ID, prefixed `sacc_`, with advertising access.
      - `include` AudienceEngagementRule[], required — Match any inclusion rule. Supply 1–10 rules. Video rules must share a retention window and cannot be combined with other sources.
        - union
          - AudienceEngagementVideoRule
            - `event` 'watched_3_seconds' | 'watched_10_seconds' | 'watched_15_seconds' | 'watched_25_percent' | 'watched_50_percent' | 'watched_75_percent' | 'watched_95_percent', required — Interaction that qualifies a person for this rule.
            - `object` 'video', required — Engagement source.
            - `platform_video_ids` string[], required
            - `retention_days` integer, required — Rolling membership window in days, from 1 to 365.
            - `social_account_id` string, required — Connected social account ID, prefixed `sacc_`, with advertising access.
          - AudienceEngagementLeadFormRule
            - `event` 'opened' | 'submitted' | 'not_submitted', required — Interaction that qualifies a person for this rule.
            - `object` 'lead_form', required — Engagement source.
            - `platform_form_ids` string[], required
            - `retention_days` integer, required — Rolling membership window in days, from 1 to 90.
            - `social_account_id` string, required — Connected social account ID, prefixed `sacc_`, with advertising access.
          - AudienceEngagementInstagramProfileRule
            - `event` 'all' | 'engaged' | 'visited' | 'messaged' | 'saved' | 'ad_liked' | 'ad_commented' | 'ad_shared' | 'ad_saved' | 'ad_cta_clicked' | 'ad_carousel_swiped' | 'organic_liked' | 'organic_commented' | 'organic_shared' | 'organic_saved' | 'organic_swiped' | 'organic_carousel_swiped', required — Interaction that qualifies a person for this rule.
            - `object` 'instagram_profile', required — Engagement source.
            - `retention_days` integer, required — Rolling membership window in days, from 1 to 730.
            - `social_account_id` string, required — Connected social account ID, prefixed `sacc_`, with advertising access.
          - AudienceEngagementFacebookPageRule
            - `event` 'engaged' | 'visited' | 'liked' | 'messaged' | 'cta_clicked' | 'saved' | 'post_interaction', required — Interaction that qualifies a person for this rule.
            - `object` 'facebook_page', required — Engagement source.
            - `retention_days` integer, required — Rolling membership window in days, from 1 to 730. Use 0 for `liked`, which tracks current likes and cannot be combined with other events.
            - `social_account_id` string, required — Connected social account ID, prefixed `sacc_`, with advertising access.
      - `platform` 'meta', required — Ad platform that maintains membership.
    - `error_message` string, nullable, required — Processing error message. `null` unless processing is partial or failed.
    - `filters` object, nullable, required — Saved Whop People filters that define membership, using the same keys as `GET /people`. `null` for uploaded lists, engagement audiences, 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 and engagement audiences.
    - `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 and engagement audiences.
    - `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' | 'engagement', required — Membership source: an uploaded CSV, Whop People filters, or social engagement.
    - `status` 'pending' | 'processing' | 'syncing' | 'ready' | 'partial' | 'failed', required — Current state of audience creation. For engagement audiences, `ready` means the rules were created on Meta; membership may still be populating. `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 and engagement audiences.
    - `updated_at` string, required — When the audience was last updated, as an ISO 8601 timestamp.
  - object
    - `data` Audience[], required
      - `audience_type` 'custom' | 'lookalike', required — Whether the audience targets a defined group of people or people similar to an existing audience.
      - `auto_refresh` boolean, required — Whether Whop rebuilds membership from saved People filters twice a day. When `false`, People audiences keep the members matched at creation. Always `false` for uploaded lists, lookalikes, and engagement audiences. Engagement membership is maintained by Meta.
      - `created_at` string, required — When the audience was created, as an ISO 8601 timestamp.
      - `engagement` AudienceEngagement, required
        - `exclude` AudienceEngagementRule[], required — Exclude anyone matching any exclusion rule. Supply 0–10 rules. Video audiences do not support exclusions; use a separate audience in ad-group exclusions.
          - union
            - AudienceEngagementVideoRule
              - …
            - AudienceEngagementLeadFormRule
              - …
            - AudienceEngagementInstagramProfileRule
              - …
            - AudienceEngagementFacebookPageRule
              - …
        - `include` AudienceEngagementRule[], required — Match any inclusion rule. Supply 1–10 rules. Video rules must share a retention window and cannot be combined with other sources.
          - union
            - AudienceEngagementVideoRule
              - …
            - AudienceEngagementLeadFormRule
              - …
            - AudienceEngagementInstagramProfileRule
              - …
            - AudienceEngagementFacebookPageRule
              - …
        - `platform` 'meta', required — Ad platform that maintains membership.
      - `error_message` string, nullable, required — Processing error message. `null` unless processing is partial or failed.
      - `filters` object, nullable, required — Saved Whop People filters that define membership, using the same keys as `GET /people`. `null` for uploaded lists, engagement audiences, 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 and engagement audiences.
      - `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 and engagement audiences.
      - `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' | 'engagement', required — Membership source: an uploaded CSV, Whop People filters, or social engagement.
      - `status` 'pending' | 'processing' | 'syncing' | 'ready' | 'partial' | 'failed', required — Current state of audience creation. For engagement audiences, `ready` means the rules were created on Meta; membership may still be populating. `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 and engagement audiences.
      - `updated_at` string, required — When the audience was last updated, as an ISO 8601 timestamp.

## Other responses

- `400` — Invalid Parameters
- `401` — Unauthorized
- `409` — Conflict

## Changes

> 60 revisions in range; 1 not diffed.

- **2026-09-08** `4fe3b2d21546` — 2 warning, 6 info
  - added the new `engagement` enum value to the `oneOf[#/components/schemas/Audience]/source_type` response property for the response status `201`
  - added the new `engagement` enum value to the `oneOf[subschema #2]/data/items/source_type` response property for the response status `201`
  - added the new optional `header` request parameter `Api-Version-Date` to all path's operations
  - added the new optional request property `engagement`
  - …4 more
- **2026-08-12** `ae20b30817de` — 1 info
  - added the non-success response with the status `409`
- **2026-08-07** `f1020c3ecda4` — 1 info
  - added the optional property `error/code` to the response with the `401` status
- **2026-08-04** `ca841fbd6786` — 1 info
  - added the new optional request property `column_mapping/ltv`
- **2026-07-26** `60bbb4a6ffbc` — 14 breaking, 10 info
  - added `#/components/schemas/Audience, subschema #2` to the response body `oneOf` list for the response status `201`
  - the response's body type changed from `object` to no type for status `201`
  - removed the required property `created_at` from the response with the `201` status
  - removed the required property `error_message` from the response with the `201` status
  - …20 more

[Full history](https://skmtc.dev/whop/apis/whop-api/changes/audiences/post.md)

---

[API](https://skmtc.dev/whop/apis/whop-api.md) · [All operations](https://skmtc.dev/whop/apis/whop-api/llms.txt) · [OpenAPI document](https://skmtc.dev/whop/apis/whop-api/revisions/ff3a76573563?raw)