Audiences

Add People

Changed on

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/{id}/add_people

Request

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

Path parameters

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.

Example request

{
  "file_id": "file_xxxxxxxxxxxxxx"
}

Response

Audience upload accepted.

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