Access tokens1

Account links1

Accounts20

Ad Campaigns9

Ad Conversion Value Rules7

Ad Groups10

Ad Pixels5

Ads8

Affiliates10

Ai chats5

API Keys7

Api Logs1

App Builds4

Apps8

Audiences5

Authorized users4

Bounties7

Bounty Submissions5

Cards6

Cashback Rules4

Chat channels3

Checkout Configurations4

Company token transactions3

Confirmation Tokens1

Course chapters5

Course lesson interactions2

Course lessons8

Course students2

Courses5

Deposits1

Dispute alerts2

Disputes6

Dm channels5

Dm members5

Domains6

Economic Intelligence2

Events4

Experiences8

Experiments8

Exports3

External Accounts10

Fee markups3

Feedback1

Files4

Forum posts4

Forums3

Identity profiles4

Invoices9

Leads4

Ledger accounts1

Ledgers3

Media2

Members5

Memberships13

Messages5

Notifications6

Partner Referral Requests6

Partners11

Payment Method Domains5

Payment methods3

Payment Quotes2

Payment Rules9

Payments14

Payout accounts1

Payout methods2

Payouts11

People2

Permissions1

Plans6

Product Affiliates1

Products7

Promo Codes6

Reactions4

Refunds2

Resolution Center Cases11

Reviews3

Setup Intents6

Shipments4

Social Accounts10

Stats6

Support channels3

Swaps4

Team Members5

Topups1

Trades3

Transfers6

Users18

Variants6

Verifications4

Waitlist Entries7

Webhooks9

Webhooks

Accounts4

Ad Campaigns2

Ad Groups1

Ads1

Cards13

Course lesson interactions1

Deposits1

Dispute alerts1

Disputes2

Entries4

Exports2

Invoices5

Ledger accounts1

Ledgers1

Members2

Memberships3

Messages1

Payments7

Payout accounts1

Payouts4

Products5

Reactions1

Refunds2

Resolution Center Cases3

Setup Intents3

Shipments2

Swaps1

Transfers3

Variants3

Verifications2

Audiences

Create Audience

Changed on Oct 6, 2026

Creates a custom audience from a customer list, your account's Whop People data, or engagement with videos, lead forms, Instagram profiles, or Facebook pages, or a lookalike audience that reaches people similar to an existing one. Processing runs asynchronously. A custom audience returns one audience; a lookalike returns the requested similarity bands in data.

post/audiences

Request

Base URL: https://api.whop.com/api/v1
URL: https://api.whop.com/api/v1/audiences
Auth: HTTP bearer

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'

Audience type. Defaults to custom.

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

CSV 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"}. Activity dates event_from and event_to are inclusive and remain fixed on refresh. Use event_within_days, first_seen_within_days or last_seen_within_days for a rolling window. 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. For example, 3 audiences at 6% creates 0–2%, 2–4%, and 4–6% bands.

source_audience_idstring

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.

Example request

{
  "account_id": "biz_xxxxxxxxxxxxxx",
  "engagement": {
    "include": [
      {
        "event": "engaged",
        "external_account_id": "sacc_xxxxxxxxxxxxxx",
        "object": "facebook_page",
        "retention_days": 30
      }
    ],
    "platform": "meta"
  },
  "name": "Page engagers",
  "source_type": "engagement"
}

Response

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

Example response

{
  "audience_type": "lookalike",
  "created_at": "2026-01-01T12:00:00.000Z",
  "engagement": {
    "exclude": [
      {
        "event": "watched_50_percent",
        "external_account_id": "sacc_xxxxxxxxxxxxxx",
        "object": "video",
        "platform_video_ids": [
          "444"
        ],
        "retention_days": 30
      }
    ],
    "include": [
      {
        "event": "watched_50_percent",
        "external_account_id": "sacc_xxxxxxxxxxxxxx",
        "object": "video",
        "platform_video_ids": [
          "444"
        ],
        "retention_days": 30
      }
    ],
    "platform": "meta"
  },
  "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"
}

Changes

Oct 6, 20268d734102c0b6 Revision changes
- breaking
  added the new required request property ///////
- breaking
  added the new required request property ///////
- breaking
  added the new required request property ///////
- breaking
  added the new required request property ///////
- breaking
  added the new required request property ///////
- breaking
  added the new required request property ///////
- breaking
  added the new required request property ///////
- breaking
  added the new required request property ///////
- breaking
  removed the required property /////////////// from the response with the status
- breaking
  removed the required property /////////////// from the response with the status
- breaking
  removed the required property /////////////// from the response with the status
- breaking
  removed the required property /////////////// from the response with the status
- breaking
  removed the required property /////////////// from the response with the status
- breaking
  removed the required property /////////////// from the response with the status
- breaking
  removed the required property /////////////// from the response with the status
- breaking
  removed the required property /////////////// from the response with the status
- breaking
  removed the required property ////////////// from the response with the status
- breaking
  removed the required property ////////////// from the response with the status
- breaking
  removed the required property ////////////// from the response with the status
- breaking
  removed the required property ////////////// from the response with the status
- breaking
  removed the required property ////////////// from the response with the status
- breaking
  removed the required property ////////////// from the response with the status
- breaking
  removed the required property ////////////// from the response with the status
- breaking
  removed the required property ////////////// from the response with the status
- warning
  removed the request property ///////
- warning
  removed the request property ///////
- warning
  removed the request property ///////
- warning
  removed the request property ///////
- warning
  removed the request property ///////
- warning
  removed the request property ///////
- warning
  removed the request property ///////
- warning
  removed the request property ///////
- info
  added the required property /////////////// to the response with the status
- info
  added the required property /////////////// to the response with the status
- info
  added the required property /////////////// to the response with the status
- info
  added the required property /////////////// to the response with the status
- info
  added the required property /////////////// to the response with the status
- info
  added the required property /////////////// to the response with the status
- info
  added the required property /////////////// to the response with the status
- info
  added the required property /////////////// to the response with the status
- info
  added the required property ////////////// to the response with the status
- info
  added the required property ////////////// to the response with the status
- info
  added the required property ////////////// to the response with the status
- info
  added the required property ////////////// to the response with the status
- info
  added the required property ////////////// to the response with the status
- info
  added the required property ////////////// to the response with the status
- info
  added the required property ////////////// to the response with the status
- info
  added the required property ////////////// to the response with the status
Sep 8, 20264fe3b2d21546 Revision changes
- warning
  added the new engagement enum value to the //// response property for the response status
- warning
  added the new engagement enum value to the /// response property for the response status
- info
  added the new optional header request parameter Api-Version-Date to all path's operations
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the non-success response with the status
- info
  added the required property //// to the response with the status
- info
  added the required property /// to the response with the status

Operation history (7 revisions)