Audience

An Audience is a reusable group of people to include or exclude when targeting ads. Build custom audiences from customer lists, Whop People data, or social engagement, and create lookalikes to reach people similar to an existing audience. Use the Audiences API to create, list, and delete audiences and monitor asynchronous processing. Meta engagement sources include videos, lead forms, Instagram profiles, and Facebook pages. Engagement membership updates on Meta; Whop People audiences can refresh automatically or keep a snapshot.

Endpoints

Endpoint	Request
List Audiences	GET `/audiences`
Create Audience	POST `/audiences`
Add People	POST `/audiences/{id}/add_people`
Update Audience	PATCH `/audiences/{id}`
Delete Audience	DELETE `/audiences/{id}`

Attributes

string

required

Audience ID, prefixed adaud_.

string

required

Whether the audience targets a defined group of people or people similar to an existing audience.Available options: custom, lookalike

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.

string

required

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

object | null

required

Social engagement rules maintained by the ad platform. null for other audience sources.

Properties

video or lead_form or instagram_profile or facebook_page[]

required

Exclude anyone matching any exclusion rule. Supply 0–10 rules. Video audiences do not support exclusions; use a separate audience in ad-group exclusions.

video or lead_form or instagram_profile or facebook_page[]

required

Match any inclusion rule. Supply 1–10 rules. Video rules must share a retention window and cannot be combined with other sources.

string

required

Ad platform that maintains membership.Available options: meta

string | null

required

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

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.

string | null

required

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

number | null

required

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

number | null

required

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

object[]

required

Estimated match rates by ad platform. Empty for engagement audiences and audiences not sent to a supported platform.

Properties

number | null

required

Lower bound of the estimated match rate percentage. null until available.

string

required

The ad platform that provided the match-rate estimate.Available options: meta

string | null

required

Availability of the estimated match rate.Available options: calculating, available, unavailable

number | null

required

Upper bound of the estimated match rate percentage. null until available.

number

required

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

string

required

Audience display name.

string[]

required

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

number

required

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

number

required

Processing progress from 0 to 100.

string | null

required

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

string

required

Membership source: an uploaded CSV, Whop People filters, or social engagement.Available options: csv_upload, people_filter, engagement

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

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.

string

required

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

Audience

{
	"id": "adaud_PastPurchasers123",
	"name": "Past purchasers",
	"status": "ready",
	"audience_type": "custom",
	"source_type": "people_filter",
	"source_audience_id": null,
	"lookalike_ratio": null,
	"lookalike_starting_ratio": null,
	"total_rows": 2500,
	"processed_rows": 2500,
	"matched_rows": 1830,
	"progress_percent": 100,
	"error_message": null,
	"platform_audience_ids": ["120246230799130686"],
	"engagement": null,
	"filters": {
		"has_purchased": true,
		"country": "US"
	},
	"auto_refresh": true,
	"last_refreshed_at": "2025-12-01T01:00:00Z",
	"match_rates": [
		{
			"platform": "meta",
			"status": "available",
			"lower_bound": 68.2,
			"upper_bound": 74.5
		}
	],
	"created_at": "2025-12-01T00:00:00Z",
	"updated_at": "2025-12-01T01:00:00Z"
}

Introduction

Reference

Webhooks & Events

Core Resources

Notifications

Payments

Money

Commerce

Partners

Workforce

Tracking

Ads

Media

Identity

Developer

Endpoints

Attributes

​Endpoints

​Attributes

Endpoints

Attributes