Audiences

Update Audience

Changed on

Renames an audience. For an audience built from People filters that keeps itself up to date, pass filters to replace them, which rebuilds membership immediately. Whether an audience auto refreshes is set when it is created.

patch/audiences/{id}

Request

  • Base URL: https://api.whop.com/api/v1
  • URL: https://api.whop.com/api/v1/audiences/{id}
  • Auth: HTTP bearer

Path parameters

idstring required

Audience ID, prefixed adaud_.

Request body

filtersobject

Replaces the People filters that define membership. The whole definition is replaced rather than merged, so send every filter you want to keep — a filter you leave out stops applying. Keys and values are the ones GET /people accepts, such as an os of iOS or a country of US, and at least one filter is required. Date filters must be rolling windows — first_seen_within_days or last_seen_within_days — so the audience re-anchors every time it rebuilds; fixed dates such as first_seen_after are rejected, as is audience_id. An array value holds at most 500 items, and each value at most 10 KB. Only an audience with a source_type of people_filter and auto_refresh of true accepts filters: an uploaded list has no filters to replace, and with auto refresh off the audience keeps the people it matched when it was built, so create a new audience instead.

namestring

New audience display name. A blank value is ignored rather than clearing the name.

Example request

{
  "filters": {
    "country": "US",
    "last_seen_within_days": 60
  },
  "name": "Austin visitors, last 60 days"
}

Response

Audience updated.

audience_type'custom' | 'lookalike' required

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

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

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

Saved Whop People filters that define membership, using the same keys as GET /people. null for uploaded lists, engagement audiences, 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 and engagement audiences.

namestring required

Audience display name.

platform_audience_idsstring[] required
processed_rowsnumber required

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

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' | 'engagement' required

Membership source: an uploaded CSV, Whop People filters, or social engagement.

status'pending' | 'processing' | 'syncing' | 'ready' | 'partial' | 'failed' 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.

total_rowsnumber required

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

updated_atstring required

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

Example response

{
  "audience_type": "lookalike",
  "created_at": "2026-01-01T12:00:00.000Z",
  "engagement": {
    "exclude": [
      {
        "event": "watched_50_percent",
        "external_account_id": "sacc_xxxxxxxxxxxxxx",
        "object": "video",
        "platform_video_ids": [
          "444"
        ],
        "retention_days": 30
      }
    ],
    "include": [
      {
        "event": "watched_50_percent",
        "external_account_id": "sacc_xxxxxxxxxxxxxx",
        "object": "video",
        "platform_video_ids": [
          "444"
        ],
        "retention_days": 30
      }
    ],
    "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

  • 8d734102c0b6Revision changes
    • breaking

      removed the required property /////////// from the response with the status

    • breaking

      removed the required property /////////// from the response with the status

    • breaking

      removed the required property /////////// from the response with the status

    • breaking

      removed the required property /////////// from the response with the status

    • breaking

      removed the required property /////////// from the response with the status

    • breaking

      removed the required property /////////// from the response with the status

    • breaking

      removed the required property /////////// from the response with the status

    • breaking

      removed the required property /////////// from the response with the status

    • info

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

    • info

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

    • info

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

    • info

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

    • info

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

    • info

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

    • info

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

    • info

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

  • 4fe3b2d21546Revision changes
    • warning

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

    • info

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

    • info

      added the required property to the response with the status