---
title: "Update audience via Copilot"
method: PATCH
path: "/api/servicepool/copilot/audiences/{identifier}"
tags: ["audiences"]
---

# Update audience via Copilot

`PATCH /api/servicepool/copilot/audiences/{identifier}`

## Request

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

## Path parameters

- `identifier` string, uuid, required

## Request body

- AudienceDtoCopilotInput
  - `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
  - `filters` array[], required: Collection of filter groups which are logically ORed together
    - object[]: Collection of filter groups which are logically ANDed together
      - `id` union, required: The unique identifier of the filter.
        - 'hireApplicants.rejectionReason' | 'hireApplicants.rejectionDate' | 'hireApplicants.stage.title' | 'hireApplicants.createdAt' | 'hireApplicants.opening.uuid' | 'hireApplicants.positionUuid' | 'hireApplicants.concepts.values.conceptOptionUuid' | 'wxWorkers.employmentStatus.type' | 'wxWorkers.employmentStatus.subtype' | 'wxWorkers.terminationDate' | 'lastActivityAt' | 'latestAiInterview.completedAt' | 'latestAiInterview.assessmentScore' | 'homeAddress.city' | 'homeAddress.county' | 'homeAddress.state' | 'homeAddress.zip' | 'talentType'
        - string
      - `operator` 'eq' | 'ne' | 'regex' | 'regex:startsWith' | 'regex:doesNotStartWith' | 'regex:endsWith' | 'regex:doesNotEndWith' | 'regex:contains' | 'regex:doesNotContain' | 'regex:exists' | 'regex:doesNotExist' | 'regex:isEmpty' | 'regex:isNotEmpty' | 'or:isEmptyOrMissing' | 'in' | 'nin' | 'all' | 'gt' | 'gte' | 'lt' | 'lte' | 'within:lastDays' | 'older:thanDays', required: The operator of the filter. 'in' and 'nin' are used for select and array filters, but 'all' is only used for array filters. Any operator starting with 'regex' is only usable for string filters. 'gt', 'gte', 'lt', 'lte' are only usable for number or date filters. 'eq' is used for string, number, boolean, and date filters. 'ne' is used for string, number, and boolean filters. 'or:isEmptyOrMissing' is used for string and date filters.
      - `type` 'string' | 'array' | 'number' | 'date' | 'boolean' | 'select', required: The type of the filter. 'hireApplicants.rejectionReason', 'hireApplicants.stage.title', 'hireApplicants.positionUuid', 'hireApplicants.opening.uuid', 'hireApplicants.concepts.values.conceptOptionUuid', 'wxWorkers.employmentStatus.type', 'wxWorkers.employmentStatus.subtype', and 'talentType' are select type. 'homeAddress.city', 'homeAddress.county', 'homeAddress.state', and 'homeAddress.zip' are string type. 'hireApplicants.createdAt' and 'hireApplicants.rejectionDate' are date type. Custom attribute filters are based on the type of the custom attribute.
      - `value` union, required: The value of the filter. For 'talentType', value MUST be an array containing only: "worker", "applicant", or "prospect". Do NOT use "wxWorker", "Worker", "Applicant", or "Prospect".
        - string
        - number
        - boolean
        - string[]
        - number[]
        - boolean[]
  - `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 `200`

Audience updated. meta.planLimit carries a notice when the company plan hides part of the filter.

- object
  - `data` 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)