Create

Email,Phone,First Name,Last Name,Country,LTV
jenny.nuo@example.com,+14155550123,Jenny,Nuo,US,249.50

{
	"account_id": "biz_xxxxxxxxxxxxxx",
	"name": "Past purchasers",
	"column_mapping": {
		"email": "Email",
		"phone": "Phone",
		"first_name": "First Name",
		"last_name": "Last Name",
		"country": "Country",
		"ltv": "LTV"
	},
	"file_id": "file_xxxxxxxxxxxxx"
}

{
  "audience_type": "lookalike",
  "auto_refresh": false,
  "created_at": "2026-01-01T12:00:00.000Z",
  "engagement": {
    "exclude": [
      {
        "event": "watched_50_percent",
        "object": "video",
        "platform_video_ids": [
          "444"
        ],
        "retention_days": 30,
        "social_account_id": "sacc_xxxxxxxxxxxxxx"
      }
    ],
    "include": [
      {
        "event": "watched_50_percent",
        "object": "video",
        "platform_video_ids": [
          "444"
        ],
        "retention_days": 30,
        "social_account_id": "sacc_xxxxxxxxxxxxxx"
      }
    ],
    "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
    }
  ],
  "matched_rows": 0,
  "name": "Past purchasers Lookalike 2–4%",
  "platform_audience_ids": [
    "120246230799130687"
  ],
  "processed_rows": 0,
  "progress_percent": 0,
  "source_audience_id": "adaud_xxxxxxxxxxxxxx",
  "source_type": "csv_upload",
  "status": "pending",
  "total_rows": 0,
  "updated_at": "2026-01-01T12:00:00.000Z"
}

{
  "error": {
    "message": "account_id is required",
    "type": "bad_request",
    "code": "<string>"
  }
}

{
  "error": {
    "message": "account_id is required",
    "type": "bad_request",
    "code": "<string>"
  }
}

{
  "error": {
    "message": "account_id is required",
    "type": "bad_request",
    "code": "<string>"
  }
}

POST

audiences

Email,Phone,First Name,Last Name,Country,LTV
jenny.nuo@example.com,+14155550123,Jenny,Nuo,US,249.50

{
	"account_id": "biz_xxxxxxxxxxxxxx",
	"name": "Past purchasers",
	"column_mapping": {
		"email": "Email",
		"phone": "Phone",
		"first_name": "First Name",
		"last_name": "Last Name",
		"country": "Country",
		"ltv": "LTV"
	},
	"file_id": "file_xxxxxxxxxxxxx"
}

{
  "audience_type": "lookalike",
  "auto_refresh": false,
  "created_at": "2026-01-01T12:00:00.000Z",
  "engagement": {
    "exclude": [
      {
        "event": "watched_50_percent",
        "object": "video",
        "platform_video_ids": [
          "444"
        ],
        "retention_days": 30,
        "social_account_id": "sacc_xxxxxxxxxxxxxx"
      }
    ],
    "include": [
      {
        "event": "watched_50_percent",
        "object": "video",
        "platform_video_ids": [
          "444"
        ],
        "retention_days": 30,
        "social_account_id": "sacc_xxxxxxxxxxxxxx"
      }
    ],
    "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
    }
  ],
  "matched_rows": 0,
  "name": "Past purchasers Lookalike 2–4%",
  "platform_audience_ids": [
    "120246230799130687"
  ],
  "processed_rows": 0,
  "progress_percent": 0,
  "source_audience_id": "adaud_xxxxxxxxxxxxxx",
  "source_type": "csv_upload",
  "status": "pending",
  "total_rows": 0,
  "updated_at": "2026-01-01T12:00:00.000Z"
}

{
  "error": {
    "message": "account_id is required",
    "type": "bad_request",
    "code": "<string>"
  }
}

{
  "error": {
    "message": "account_id is required",
    "type": "bad_request",
    "code": "<string>"
  }
}

{
  "error": {
    "message": "account_id is required",
    "type": "bad_request",
    "code": "<string>"
  }
}

Upload the customer CSV with POST /files on the Legacy API, then pass the returned file_... ID as file_id. column_mapping tells Whop which CSV header contains each identity field. Headers can be custom, but Whop skips rows that lack both email and phone. After creating the audience, poll List Audiences until status is ready, partial, or failed. Map ltv to a column of per-customer lifetime values to build a value-based audience. Lookalikes created from it favor people similar to your highest-value customers.

Email,Phone,First Name,Last Name,Country,LTV
jenny.nuo@example.com,+14155550123,Jenny,Nuo,US,249.50

{
	"account_id": "biz_xxxxxxxxxxxxxx",
	"name": "Past purchasers",
	"column_mapping": {
		"email": "Email",
		"phone": "Phone",
		"first_name": "First Name",
		"last_name": "Last Name",
		"country": "Country",
		"ltv": "LTV"
	},
	"file_id": "file_xxxxxxxxxxxxx"
}

Authorizations

Authorization

string

header

required

An Account API key, account-scoped JWT, App API key, or user OAuth token. Prepend the key or token with Bearer, for example Bearer ***************************.

Headers

Idempotency-Key

string

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

Maximum string length: 255

Example:

"d9105228-4a08-46b1-8b91-42fed586d383"

Api-Version-Date

string

Pins the request to a dated API version.

Example:

"2026-09-15"

Body

application/json

account_id

string

required

Account ID, prefixed biz_.

Example:

"biz_xxxxxxxxxxxxxx"

audience_type

enum<string>

Audience type. Defaults to custom.

Available options:

custom,

lookalike

Example:

"lookalike"

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.

Example:

true

column_mapping

object

CSV audiences only. Maps supported identity fields to CSV column headers. Map at least one of email or phone.

Show child attributes

count

integer

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

Example:

3

engagement

object

Rules for membership based on social engagement. Requires a connected social account with advertising access.

Show child attributes

file_id

string

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

Example:

"eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

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.

Example:

{
  "country": "US",
  "last_seen_within_days": 30
}

name

string

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

Example:

"Page engagers"

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.

Example:

6

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.

Example:

"adaud_xxxxxxxxxxxxxx"

source_type

enum<string>

Custom audience source. Inferred from engagement, then filters, otherwise defaults to csv_upload. Supply only the fields for the selected source.

Available options:

csv_upload,

people_filter,

engagement

Example:

"engagement"

Response

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

Option 1
Option 2

audience_type

enum<string>

required

Whether the audience targets a defined group of people or people similar to an existing audience.

Available options:

custom,

lookalike

Example:

"lookalike"

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.

Example:

false

created_at

string

required

When the audience was created, as an ISO 8601 timestamp.

Example:

"2026-01-01T12:00:00.000Z"

engagement

object | null

required

Social engagement rules maintained by the ad platform. null for other audience sources.

Show child attributes

error_message

string | null

required

Processing error message. null unless processing is partial or failed.

Example:

"412 of 1,000 rows had no email or phone number, so the list could not be matched."

filters

object | null

required

Saved Whop People filters that define membership, using the same keys as GET /people. null for uploaded lists, engagement audiences, and lookalikes.

Example:

{
  "country": "US",
  "last_seen_within_days": 30
}

string

required

Audience ID, prefixed adaud_.

Example:

"adaud_xxxxxxxxxxxxxx"

last_refreshed_at

string | null

required

When the audience membership was last rebuilt, as an ISO 8601 timestamp. null until the first build completes.

Example:

"2026-01-01T12:00:00.000Z"

lookalike_ratio

number | null

required

For lookalikes: the upper bound of the similarity band as a fraction (0.02 = top 2%). null for custom audiences.

Example:

0.04

lookalike_starting_ratio

number | null

required

For lookalikes: the lower bound of the similarity band as a fraction. null for custom audiences and first-tier lookalikes.

Example:

0.02

match_rates

object[]

required

Show child attributes

matched_rows

number

required

Members successfully uploaded to connected ad accounts. Always 0 for lookalikes and engagement audiences.

Example:

0

name

string

required

Audience display name.

Example:

"Past purchasers Lookalike 2–4%"

platform_audience_ids

string[]

required

External audience IDs created on connected ad platforms, such as Meta.

processed_rows

number

required

Members processed from the source so far. Always 0 for lookalikes and engagement audiences.

Example:

0

progress_percent

number

required

Processing progress from 0 to 100.

Example:

0

source_audience_id

string | null

required

For lookalikes: the audience this lookalike was built from. null for custom audiences.

Example:

"adaud_xxxxxxxxxxxxxx"

source_type

enum<string>

required

Membership source: an uploaded CSV, Whop People filters, or social engagement.

Available options:

csv_upload,

people_filter,

engagement

Example:

"csv_upload"

status

enum<string>

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.

Available options:

pending,

processing,

syncing,

ready,

partial,

failed

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.

Example:

0

updated_at

string

required

When the audience was last updated, as an ISO 8601 timestamp.

Example:

"2026-01-01T12:00:00.000Z"

Introduction

Reference

Webhooks & Events

Core Resources

Notifications

Payments

Money

Commerce

Partners

Workforce

Tracking

Ads

Media

Identity

Developer

Authorizations

Headers

Body

Response