Skip to main content
POST
JavaScript

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"

Path Parameters

audience_id
string
required

Audience ID, prefixed adaud_.

Body

application/json
file_id
string
required

The new customer CSV — a file id (file_...) returned by POST /files. Its headers must match the audience's saved column mapping.

Response

Audience upload accepted.

audience_type
enum<string>
required

custom = a customer list (uploaded, or built from saved People filters); lookalike = Meta lookalike built from a custom audience.

Available options:
custom,
lookalike
Example:

"custom"

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

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

filters
object | null
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 | null
required

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

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

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.

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.

source_type
enum<string>
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.

Available options:
csv_upload,
people_filter
Example:

"csv_upload"

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