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

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

{
  "audience_type": "custom",
  "created_at": "<string>",
  "error_message": "<string>",
  "id": "<string>",
  "lookalike_ratio": 123,
  "lookalike_starting_ratio": 123,
  "match_rates": [
    {
      "lower_bound": 123,
      "platform": "meta",
      "status": "calculating",
      "upper_bound": 123
    }
  ],
  "matched_rows": 123,
  "name": "<string>",
  "platform_audience_ids": [
    "<string>"
  ],
  "processed_rows": 123,
  "progress_percent": 123,
  "source_audience_id": "<string>",
  "total_rows": 123,
  "updated_at": "<string>"
}

{
  "error": {
    "message": "<string>",
    "type": "<string>"
  }
}

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 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

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

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

{
  "audience_type": "custom",
  "created_at": "<string>",
  "error_message": "<string>",
  "id": "<string>",
  "lookalike_ratio": 123,
  "lookalike_starting_ratio": 123,
  "match_rates": [
    {
      "lower_bound": 123,
      "platform": "meta",
      "status": "calculating",
      "upper_bound": 123
    }
  ],
  "matched_rows": 123,
  "name": "<string>",
  "platform_audience_ids": [
    "<string>"
  ],
  "processed_rows": 123,
  "progress_percent": 123,
  "source_audience_id": "<string>",
  "total_rows": 123,
  "updated_at": "<string>"
}

{
  "error": {
    "message": "<string>",
    "type": "<string>"
  }
}

Pass a direct upload ID from the standard media upload endpoint as file_id. column_mapping tells Whop which CSV header contains each identity field. Headers can be custom, but rows missing both email and phone are skipped. After creating the audience, poll List Audiences until status is ready, partial, or failed.

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

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

Authorizations

Authorization

string

header

required

A company API key, company scoped JWT, app API key, or user OAuth token. You must prepend your key/token with the word 'Bearer', which will look like Bearer ***************************

Body

application/json

account_id

string

required

Account ID, prefixed biz_.

audience_type

enum<string>

What to create. Defaults to custom (CSV upload).

Available options:

custom,

lookalike

column_mapping

object

Custom 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).

file_id

string

Custom audiences only. Direct upload ID from the standard media upload endpoint.

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

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

Option 1
Option 2

audience_type

enum<string>

required

custom = uploaded customer list; lookalike = Meta lookalike built from a custom audience.

Available options:

custom,

lookalike

Example:

"custom"

created_at

string

required

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

error_message

string | null

required

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

string

required

Audience ID, prefixed adaud_.

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.

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.

match_rates

object[]

required

Show child attributes

matched_rows

number

required

Rows successfully uploaded to connected ad accounts. Always 0 for lookalikes.

name

string

required

Audience display name.

platform_audience_ids

string[]

required

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

processed_rows

number

required

Rows processed from the uploaded CSV. Always 0 for lookalikes.

progress_percent

number

required

Processing progress from 0 to 100.

source_audience_id

string | null

required

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

status

enum<string>

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.

Available options:

pending,

processing,

syncing,

ready,

partial,

failed

total_rows

number

required

Total rows detected in the uploaded CSV. Always 0 for lookalikes.

updated_at

string

required

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

Audience

List Audiences

⌘I

Introduction

Reference

Core Resources

Money

Commerce

Partners

Workforce

Tracking

Ads

Media

Identity

Developer

Create Audience

Authorizations

Body

Response