Skip to main content
POST
Legacy API의 POST /files로 고객 CSV를 업로드한 다음, 반환된 file_... ID를 file_id로 전달하세요. column_mapping은 각 식별 필드가 어느 CSV 헤더에 들어 있는지 Whop에 알려줍니다. 헤더 이름은 자유롭게 지정할 수 있지만, Whop은 이메일과 전화번호가 모두 없는 행을 건너뜁니다. 오디언스를 생성한 후 status가 ready, partial 또는 failed가 될 때까지 오디언스 목록 조회를 폴링하세요. 고객별 생애 가치(LTV)가 담긴 열에 ltv를 매핑하면 가치 기반 오디언스를 만들 수 있습니다. 이 오디언스로 생성한 유사 오디언스는 가치가 가장 높은 고객과 비슷한 사람들을 우선합니다.

인증

Authorization
string
header
필수

An Account API key, an App API key, an account access token, an account-scoped user token, or a user OAuth token. Prepend the key or token with Bearer, for example Bearer ***************************. See Auth & API keys for how to get each one.

Scopes

audience:update

헤더

Idempotency-Key
string

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

Maximum string length: 255
예시:

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

Api-Version-Date
string

Pins the request to a dated API version.

예시:

"2026-11-17"

본문

application/json
account_id
string
필수

Account ID, prefixed biz_.

예시:

"biz_xxxxxxxxxxxxxx"

audience_type
enum<string>

Audience type. Defaults to custom.

사용 가능한 옵션:
custom,
lookalike
예시:

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

예시:

true

column_mapping
object

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

count
integer

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

예시:

3

file_id
string

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

예시:

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

예시:
name
string

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

예시:

"Austin visitors, last 30 days"

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.

예시:

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.

예시:

"adaud_xxxxxxxxxxxxxx"

source_type
enum<string>

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

사용 가능한 옵션:
csv_upload,
people_filter
예시:

"csv_upload"

응답

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

audience_type
enum<string>
필수

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

사용 가능한 옵션:
custom,
lookalike
예시:

"lookalike"

auto_refresh
boolean
필수

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.

예시:

false

created_at
string
필수

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

예시:

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

error_message
string | null
필수

Why a pending audience hasn't started, or why a partial or failed one isn't fully built. null when there is nothing to report.

예시:

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

filters
object | null
필수

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

예시:
id
string
필수

Audience ID, prefixed adaud_.

예시:

"adaud_xxxxxxxxxxxxxx"

last_refreshed_at
string | null
필수

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

예시:

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

lookalike_ratio
number | null
필수

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

예시:

0.04

lookalike_starting_ratio
number | null
필수

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

예시:

0.02

match_rates
object[]
필수
matched_rows
number
필수

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

예시:

0

name
string
필수

Audience display name.

예시:

"Past purchasers Lookalike 2–4%"

platform_audience_ids
string[]
필수

Audience IDs on the ad networks Whop sends this audience to.

processed_rows
number
필수

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

예시:

0

progress_percent
number
필수

Processing progress from 0 to 100.

예시:

0

source_audience_id
string | null
필수

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

예시:

"adaud_xxxxxxxxxxxxxx"

source_type
enum<string>
필수

Membership source: an uploaded CSV, Whop People filters, or social engagement. Engagement audiences can no longer be created.

사용 가능한 옵션:
csv_upload,
people_filter,
engagement
예시:

"csv_upload"

status
enum<string>
필수

Current state of audience creation. When a pending audience is waiting on something, such as an ad account to upload to, error_message says what. When status is partial or failed, error_message explains what went wrong.

사용 가능한 옵션:
pending,
processing,
ready,
partial,
failed
total_rows
number
필수

Total members detected in the source — CSV rows for uploaded lists, matching people for automatic audiences. Always 0 for lookalikes and engagement audiences.

예시:

0

updated_at
string
필수

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

예시:

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