v9

OpenAPI 3.1.02026-08-043703845.2 MB

Audiences

Add People

Adds users from a new CSV file to an existing uploaded custom audience. The file uses the audience's saved column mapping, processing happens in the background, and existing audience members remain unchanged.

post/audiences/{audience_id}/add_people

Path parameters

audience_idstring required

Audience ID, prefixed adaud_.

Headers

Idempotency-Keystring

Example:d9105228-4a08-46b1-8b91-42fed586d383

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

Request body

file_idstring 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'custom' | 'lookalike' required

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

auto_refreshboolean 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_atstring required

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

error_messagestring nullable required

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

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

idstring required

Audience ID, prefixed adaud_.

last_refreshed_atstring nullable required

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

lookalike_rationumber nullable required

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

lookalike_starting_rationumber nullable required

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

matched_rowsnumber required

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

namestring required

Audience display name.

platform_audience_idsstring[] required

processed_rowsnumber required

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

progress_percentnumber required

Processing progress from 0 to 100.

source_audience_idstring nullable required

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

source_type'csv_upload' | 'people_filter' 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.

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.

total_rowsnumber required

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

updated_atstring required

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

Example response

{
  "audience_type": "custom",
  "match_rates": [
    {
      "platform": "meta",
      "status": "calculating"
    }
  ],
  "source_type": "csv_upload"
}