---
title: "Create one or multiple audiences"
method: POST
path: "/api/servicepool/audiences"
tags: ["audiences"]
---

# Create one or multiple audiences

`POST /api/servicepool/audiences`

## Request

- Base URL: `https://services.fountain.com`
- URL: `https://services.fountain.com/api/servicepool/audiences`
- Auth: HTTP bearer

## Request body

- union
  - AudienceDtoInput
    - `clickRate` number: The click rate of the audience as a fractional percentage (e.g. 0.2365 for 23.65%)
    - `description` string: The description of the audience
    - `filterValues` string: The filter values of the audience
    - `filters` string: The filters of the audience
    - `name` string, required: The name of the audience
    - `openRate` number: The open rate of the audience as a fractional percentage (e.g. 0.2365 for 23.65%)
    - `proximity` object, nullable
      - `distance` number, required: The numeric distance from location
      - `unit` 'mile' | 'kilometer', required: The unit of measurement
      - `locationUuid` string, required: The unique identifier of the location to check distance against
    - `vectors` object, nullable
      - `jobMatch` object, nullable
        - `matchThreshold` number, required: The match threshold of the job match vector, as a percent from 0 to 100
        - `matchType` 'Job' | 'Opening', required: The match type of the job match vector
        - `matchUuid` string, required: The unique identifier of the job match vector
  - AudienceDtoInput[]
    - `clickRate` number: The click rate of the audience as a fractional percentage (e.g. 0.2365 for 23.65%)
    - `description` string: The description of the audience
    - `filterValues` string: The filter values of the audience
    - `filters` string: The filters of the audience
    - `name` string, required: The name of the audience
    - `openRate` number: The open rate of the audience as a fractional percentage (e.g. 0.2365 for 23.65%)
    - `proximity` object, nullable
      - `distance` number, required: The numeric distance from location
      - `unit` 'mile' | 'kilometer', required: The unit of measurement
      - `locationUuid` string, required: The unique identifier of the location to check distance against
    - `vectors` object, nullable
      - `jobMatch` object, nullable
        - `matchThreshold` number, required: The match threshold of the job match vector, as a percent from 0 to 100
        - `matchType` 'Job' | 'Opening', required: The match type of the job match vector
        - `matchUuid` string, required: The unique identifier of the job match vector

## Response `201`

One or many audiences created.

- object
  - `data` union
    - AudienceDto
      - `activeCampaignCount` number: The number of active audience campaigns
      - `archivedAt` string, date-time: The date and time the audience was archived
      - `archivedBy` string: The unique identifier of the user who archived the audience
      - `archivedVia` 'human' | 'cue' | 'system': How the audience was archived: by a person directly (human), through Cue (cue), or by Pool's own automation (system). Absent when unknown.
      - `audienceCampaignCount` number: The number of audience campaigns
      - `clickRate` number: The click rate of the audience as a fractional percentage (e.g. 0.2365 for 23.65%)
      - `clicked` number: The number of clicked messages
      - `companyUuid` string, required: The unique identifier of the company
      - `createdAt` string, date-time, required: The date and time the audience was created
      - `createdBy` string, required: The unique identifier of the user who created the audience
      - `createdVia` 'human' | 'cue' | 'system': How the audience was created: by a person directly (human), through Cue (cue), or by Pool's own automation (system). Absent when unknown.
      - `deletedAt` string, date-time: The date and time the audience was deleted
      - `deletedBy` string: The unique identifier of the user who deleted the audience
      - `deletedVia` 'human' | 'cue' | 'system': How the audience was deleted: by a person directly (human) or through Cue (cue). Absent when unknown.
      - `delivered` number: The number of delivered messages
      - `description` string: The description of the audience
      - `filterValues` string: The filter values of the audience
      - `filters` string: The filters of the audience
      - `membershipRefreshedAt` string, date-time: The date and time the async membership computation last completed. Absent means the first computation has not finished yet (the audience is still "computing").
      - `isRefreshingMembership` boolean: Whether a membership refresh is currently outstanding for this audience. Read-only and server-owned, with three states. `true`: a requested refresh has not yet completed and still shows a live claim, either a heartbeat or the request itself younger than 15 minutes. Membership lands incrementally, so a member count read while this is true is partial and non-monotonic. `false`: the last requested refresh has completed. Absent: either no refresh was ever requested for this audience, or a pending refresh has gone stale with no heartbeat or request inside the window — the refresh stalled, and the backstop or a redeliver migration re-drives it. Clients fall back to their own heuristics when absent.
      - `membershipRefreshBlocked` object: Why the last membership refresh could not evaluate this audience on V3. While set, the member count is the last completed verdict, not a final answer: `target-not-extracted` and `coverage-building` clear on their own once the target is extracted or its rows coverage is built; `target-missing` and `pipeline-unrecognized` need the audience repointed or repaired; `membership-too-large` means one synchronous door cannot splice a membership this size, and the deferred engine handles it normally; `coverage-queued` means the target waits behind other targets in the tenant's rows build queue, with `position` (targets ahead), `total` (targets queued) and `etaAt` (expected completion) as of `at`; it clears as the queue drains; `evaluation-retired` means repeated failures exhausted the retry budget and nothing retries until the audience is edited. Read-only and server-owned; cleared by the next completed refresh.
        - `reason` 'target-not-extracted' | 'target-missing' | 'coverage-building' | 'evaluation-failed' | 'pipeline-unrecognized' | 'membership-too-large' | 'coverage-queued' | 'evaluation-retired', required
        - `detail` string
        - `at` string, date-time, required
        - `position` integer
        - `total` integer
        - `etaAt` string, date-time
      - `name` string, required: The name of the audience
      - `openRate` number: The open rate of the audience as a fractional percentage (e.g. 0.2365 for 23.65%)
      - `opened` number: The number of opened messages
      - `pipeline` string: The pipeline of the audience
      - `proximity` object, nullable
        - `distance` number, required: The numeric distance from location
        - `unit` 'mile' | 'kilometer', required: The unit of measurement
        - `locationUuid` string, required: The unique identifier of the location to check distance against
      - `sent` number: The number of sent messages
      - `status` 'active' | 'archived' | 'deleted': The status of the audience
      - `talentCount` number, nullable: The number of talents in the audience. null means a count was attempted and could not be produced (budget exhaustion or a failed query) — distinct from a genuine zero. Absent means the client did not request this field.
      - `talentCountsIncomplete` boolean: Whether any talentCount in this response is unavailable, or a requested talentCount sort could not be applied. Identical on every row of a single response.
      - `updatedAt` string, date-time, required: The date and time the audience was updated
      - `updatedBy` string, required: The unique identifier of the user who updated the audience
      - `uuid` string, required: The unique identifier of the audience
      - `vectors` object, nullable
        - `jobMatch` object, nullable
          - `matchThreshold` number, required: The match threshold of the job match vector, as a percent from 0 to 100
          - `matchType` 'Job' | 'Opening', required: The match type of the job match vector
          - `matchUuid` string, required: The unique identifier of the job match vector
      - `version` number: The version of the audience
      - `isHidden` boolean: Whether the audience is hidden or not
    - AudienceDto[]
      - `activeCampaignCount` number: The number of active audience campaigns
      - `archivedAt` string, date-time: The date and time the audience was archived
      - `archivedBy` string: The unique identifier of the user who archived the audience
      - `archivedVia` 'human' | 'cue' | 'system': How the audience was archived: by a person directly (human), through Cue (cue), or by Pool's own automation (system). Absent when unknown.
      - `audienceCampaignCount` number: The number of audience campaigns
      - `clickRate` number: The click rate of the audience as a fractional percentage (e.g. 0.2365 for 23.65%)
      - `clicked` number: The number of clicked messages
      - `companyUuid` string, required: The unique identifier of the company
      - `createdAt` string, date-time, required: The date and time the audience was created
      - `createdBy` string, required: The unique identifier of the user who created the audience
      - `createdVia` 'human' | 'cue' | 'system': How the audience was created: by a person directly (human), through Cue (cue), or by Pool's own automation (system). Absent when unknown.
      - `deletedAt` string, date-time: The date and time the audience was deleted
      - `deletedBy` string: The unique identifier of the user who deleted the audience
      - `deletedVia` 'human' | 'cue' | 'system': How the audience was deleted: by a person directly (human) or through Cue (cue). Absent when unknown.
      - `delivered` number: The number of delivered messages
      - `description` string: The description of the audience
      - `filterValues` string: The filter values of the audience
      - `filters` string: The filters of the audience
      - `membershipRefreshedAt` string, date-time: The date and time the async membership computation last completed. Absent means the first computation has not finished yet (the audience is still "computing").
      - `isRefreshingMembership` boolean: Whether a membership refresh is currently outstanding for this audience. Read-only and server-owned, with three states. `true`: a requested refresh has not yet completed and still shows a live claim, either a heartbeat or the request itself younger than 15 minutes. Membership lands incrementally, so a member count read while this is true is partial and non-monotonic. `false`: the last requested refresh has completed. Absent: either no refresh was ever requested for this audience, or a pending refresh has gone stale with no heartbeat or request inside the window — the refresh stalled, and the backstop or a redeliver migration re-drives it. Clients fall back to their own heuristics when absent.
      - `membershipRefreshBlocked` object: Why the last membership refresh could not evaluate this audience on V3. While set, the member count is the last completed verdict, not a final answer: `target-not-extracted` and `coverage-building` clear on their own once the target is extracted or its rows coverage is built; `target-missing` and `pipeline-unrecognized` need the audience repointed or repaired; `membership-too-large` means one synchronous door cannot splice a membership this size, and the deferred engine handles it normally; `coverage-queued` means the target waits behind other targets in the tenant's rows build queue, with `position` (targets ahead), `total` (targets queued) and `etaAt` (expected completion) as of `at`; it clears as the queue drains; `evaluation-retired` means repeated failures exhausted the retry budget and nothing retries until the audience is edited. Read-only and server-owned; cleared by the next completed refresh.
        - `reason` 'target-not-extracted' | 'target-missing' | 'coverage-building' | 'evaluation-failed' | 'pipeline-unrecognized' | 'membership-too-large' | 'coverage-queued' | 'evaluation-retired', required
        - `detail` string
        - `at` string, date-time, required
        - `position` integer
        - `total` integer
        - `etaAt` string, date-time
      - `name` string, required: The name of the audience
      - `openRate` number: The open rate of the audience as a fractional percentage (e.g. 0.2365 for 23.65%)
      - `opened` number: The number of opened messages
      - `pipeline` string: The pipeline of the audience
      - `proximity` object, nullable
        - `distance` number, required: The numeric distance from location
        - `unit` 'mile' | 'kilometer', required: The unit of measurement
        - `locationUuid` string, required: The unique identifier of the location to check distance against
      - `sent` number: The number of sent messages
      - `status` 'active' | 'archived' | 'deleted': The status of the audience
      - `talentCount` number, nullable: The number of talents in the audience. null means a count was attempted and could not be produced (budget exhaustion or a failed query) — distinct from a genuine zero. Absent means the client did not request this field.
      - `talentCountsIncomplete` boolean: Whether any talentCount in this response is unavailable, or a requested talentCount sort could not be applied. Identical on every row of a single response.
      - `updatedAt` string, date-time, required: The date and time the audience was updated
      - `updatedBy` string, required: The unique identifier of the user who updated the audience
      - `uuid` string, required: The unique identifier of the audience
      - `vectors` object, nullable
        - `jobMatch` object, nullable
          - `matchThreshold` number, required: The match threshold of the job match vector, as a percent from 0 to 100
          - `matchType` 'Job' | 'Opening', required: The match type of the job match vector
          - `matchUuid` string, required: The unique identifier of the job match vector
      - `version` number: The version of the audience
      - `isHidden` boolean: Whether the audience is hidden or not
  - `meta` object
    - `timestamp` string, date-time, required
    - `verb` 'OPTION' | 'GET' | 'PUT' | 'POST' | 'PATCH' | 'DELETE'
    - `path` string
    - `jti` string
    - `rid` string
    - `count` number
    - `capped` boolean: The server lowered filter[limit] to its ceiling. Page with filter[skip] to read past it.
    - `status` string
    - `duration` number
    - `size` number
    - `planLimit` union: Present only when the company plan limited the result: a retention window capped by the plan, or the non-applicant rule kept on. Returned by match-setting saves, audience saves, and talent reads.
      - object
        - `code` 'retentionWindow', required
        - `windowMonths` number, required
        - `comparedWindowMonths` number, required
        - `additionalReach` number
        - `message` string, required
      - object
        - `code` 'nonApplicantRule', required
        - `message` string, required

## Other responses

- `422`: default error response
- `500`: default error response

---

[API](https://skmtc.dev/fountain/apis/worker-experience-public-api.md) - [All operations](https://skmtc.dev/fountain/apis/worker-experience-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/fountain/apis/worker-experience-public-api/revisions/6b9a31f79e22?raw)