Manage audiences

Create an audience

In the dashboard, Audience Builder guides you through topics, signals, ICP filters, and review.

POST /v1/intent/audiences
x-api-key: YOUR_API_KEY
Content-Type: application/json

{
  "name": "Marketing Directors at Tech Companies",
  "status": "draft",
  "config": {
    "topicIds": [117805, 117890, 117918],
    "minScore": 70,
    "maxScore": 99,
    "minTopicOverlap": 2,
    "filters": {
      "company.industries": {
        "values": ["software development"]
      },
      "role.seniority": {
        "values": ["director", "vp", "c_suite"]
      },
      "contact.hasBusinessEmail": true
    }
  }
}

name and config.topicIds are required. New audiences default to draft; you can create an active audience when you have audience access. Creating an audience as paused is rejected. Pause an existing audience with PATCH instead. You can save at most 50 audiences per organization. Creating a definition does not materialize contacts.

Response

{
  "data": {
    "id": "6fb81599-f601-4afe-b3ff-e8a211cae27d",
    "organizationId": "0f1815d3-6edc-4e8e-87e1-4d65ef4f1d2c",
    "name": "Marketing Directors at Tech Companies",
    "status": "draft",
    "accessType": "paid",
    "dailyRefreshEnabled": false,
    "audienceSize": 0,
    "createdAt": "2026-05-05T09:15:00.000Z",
    "updatedAt": "2026-05-05T09:15:00.000Z"
  }
}

Activate or pause

PATCH /v1/intent/audiences/{id}
x-api-key: YOUR_API_KEY
Content-Type: application/json

Activate:

{ "status": "active" }

Pause:

{ "status": "paused" }

Activating an audience can consume an audience slot. If all slots are in use, the API returns 403 SLOTS_FULL.

Update config

{
  "name": "Updated Name",
  "config": {
    "topicIds": [117805],
    "minScore": 80,
    "filters": {
      "jobTitle.include": {
        "values": ["chief financial officer", "cfo"],
        "operator": "contains",
        "mode": "any"
      }
    }
  }
}

List audiences

The dashboard’s Saved tab lists saved audience definitions and their current status, source, people count, and update date.

GET /v1/intent/audiences?status=active&limit=50
x-api-key: YOUR_API_KEY

{
  "data": [
    {
      "id": "6fb81599-f601-4afe-b3ff-e8a211cae27d",
      "name": "Marketing Directors at Tech Companies",
      "status": "active",
      "accessType": "paid",
      "dailyRefreshEnabled": true,
      "audienceSize": 151,
      "lastRefreshedAt": "2026-05-05T08:45:00.000Z",
      "createdAt": "2026-05-04T16:20:00.000Z"
    }
  ]
}

Delete an audience

DELETE /v1/intent/audiences/{id}
x-api-key: YOUR_API_KEY

Deleting an audience also deletes its associated runs, results, and exports. This cannot be undone. A consumed one-shot trial remains consumed after deletion.

Pause an audience if you only want to stop future automatic refreshes. Configuration changes affect future runs; previously completed results remain tied to their original snapshot.

Next steps

Read Audience runs to queue and monitor a materialization run.
Read Get people to retrieve results from a completed run.

Start here

Workflow guides

Topic discovery and filters

Topic lists

Audience builder

Visitor overlap and analytics

Audience results

Integrations

Destinations

Deliveries

Create an audience

Response

Activate or pause

Update config

List audiences

Delete an audience

Next steps

​Create an audience

​Response

​Activate or pause

​Update config

​List audiences

​Delete an audience

​Next steps

Create an audience

Response

Activate or pause

Update config

List audiences

Delete an audience

Next steps