Sign in
Audiences

Create Audience

Create an audience from a customer list, your account's Whop People data, or engagement with videos, lead forms, Instagram profiles, or Facebook pages. Create lookalike audiences to reach people similar to an existing audience. Processing runs asynchronously. Custom creation returns one audience; lookalike creation returns the requested similarity bands in data.

post/audiences

Headers

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

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

Request body

account_idstring required

Account ID, prefixed biz_.

audience_type'custom' | 'lookalike'

Audience type. Defaults to custom.

auto_refreshboolean

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.

countinteger

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

file_idstring

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

filtersobject

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.

namestring

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

percentageinteger

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.

source_audience_idstring

Lookalikes only. The ready custom audience (adaud_) to build from; uploaded and People audiences need at least 100 matched people. Meta validates engagement audience eligibility when creating the lookalike.

source_type'csv_upload' | 'people_filter' | 'engagement'

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

Example request

{
  "account_id": "biz_xxxxxxxxxxxxxx",
  "engagement": {
    "include": [
      {
        "event": "engaged",
        "object": "facebook_page",
        "retention_days": 30,
        "social_account_id": "sacc_xxxxxxxxxxxxxx"
      }
    ],
    "platform": "meta"
  },
  "name": "Page engagers",
  "source_type": "engagement"
}

Response

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

OR

Example response

{
  "audience_type": "lookalike",
  "created_at": "2026-01-01T12:00:00.000Z",
  "engagement": {
    "exclude": [
      {
        "event": "watched_50_percent",
        "object": "video",
        "platform_video_ids": [
          "444"
        ],
        "retention_days": 30,
        "social_account_id": "sacc_xxxxxxxxxxxxxx"
      }
    ],
    "include": [
      {
        "event": "watched_50_percent",
        "object": "video",
        "platform_video_ids": [
          "444"
        ],
        "retention_days": 30,
        "social_account_id": "sacc_xxxxxxxxxxxxxx"
      }
    ],
    "platform": "meta"
  },
  "error_message": "412 of 1,000 rows had no email or phone number, so the list could not be matched.",
  "filters": {
    "country": "US",
    "last_seen_within_days": 30
  },
  "id": "adaud_xxxxxxxxxxxxxx",
  "last_refreshed_at": "2026-01-01T12:00:00.000Z",
  "lookalike_ratio": 0.04,
  "lookalike_starting_ratio": 0.02,
  "match_rates": [
    {
      "lower_bound": 40,
      "platform": "meta",
      "status": "available",
      "upper_bound": 50
    }
  ],
  "name": "Past purchasers Lookalike 2–4%",
  "platform_audience_ids": [
    "120246230799130687"
  ],
  "source_audience_id": "adaud_xxxxxxxxxxxxxx",
  "source_type": "csv_upload",
  "updated_at": "2026-01-01T12:00:00.000Z"
}

Changes

Changed in 6 of the 74 revisions of this API.16220

  • 4fe3b2d2154626See the full diff
    • ●

      added the new engagement enum value to the //// response property for the response status

      response-property-enum-value-added

    • ●

      added the new engagement enum value to the /// response property for the response status

      response-property-enum-value-added

    • ○

      added the new optional header request parameter Api-Version-Date to all path's operations

      new-optional-request-default-parameter-to-existing-path

    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      added the non-success response with the status

      response-non-success-status-added

    • ○

      added the required property //// to the response with the status

      response-required-property-added

    • ○

      added the required property /// to the response with the status

      response-required-property-added

    This revision also has 2 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • ae20b30817de1See the full diff
    • ○

      added the non-success response with the status

      response-non-success-status-added

  • f1020c3ecda41See the full diff
    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    This revision also has 9 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • ca841fbd67861See the full diff
    • ○

      added the new optional request property /

      new-optional-request-property

    This revision also has 6 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 60bbb4a6ffbc1410See the full diff
    • ▲

      added subschema #2 to the response body oneOf list for the response status

      response-body-one-of-added

    • ▲

      the response's body type changed from object to no type for status

      response-body-type-changed

    • ▲

      removed the required property from the response with the status

      response-required-property-removed

    • ▲

      removed the required property from the response with the status

      response-required-property-removed

    • ▲

      removed the required property from the response with the status

      response-required-property-removed

    • ▲

      removed the required property from the response with the status

      response-required-property-removed

    • ▲

      removed the required property from the response with the status

      response-required-property-removed

    • ▲

      removed the required property from the response with the status

      response-required-property-removed

    • ▲

      removed the required property from the response with the status

      response-required-property-removed

    • ▲

      removed the required property from the response with the status

      response-required-property-removed

    • ▲

      removed the required property from the response with the status

      response-required-property-removed

    • ▲

      removed the required property from the response with the status

      response-required-property-removed

    • ▲

      removed the required property from the response with the status

      response-required-property-removed

    • ▲

      removed the required property from the response with the status

      response-required-property-removed

    • ○

      added the new optional header request parameter Idempotency-Key

      new-optional-request-parameter

    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      the request property became optional

      request-property-became-optional

    • ○

      the request property became optional

      request-property-became-optional

    • ○

      the request property became optional

      request-property-became-optional

    This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 3a06a605784b21See the full diff
    • ▲

      the response's property type changed from number to string for status

      response-property-type-changed

    • ▲

      the response's property type changed from number to string for status

      response-property-type-changed

    • ○

      added the required property to the response with the status

      response-required-property-added

Of the 74 revisions, 1 has no diff computed.