Skip to main content
POST
TypeScript

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-11-1"

Path Parameters

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.

Example:

"file_xxxxxxxxxxxxxx"

Response

Audience upload accepted.

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.

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:
id
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
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"