List audiences
Returns the workspace's saved audiences ordered by name, keyset-paginated. An audience is a rule set over your customers, defined once and pointed at by promotions.
query Parameters
limitPage size. Values above the server-side cap are clamped (standard default 50, cap 200; a few document-heavy lists use larger windows). Invalid values fall back to the default.
cursorOpaque continuation token from the previous response's pagination.cursor. Omit for the first page. Cursors are stateless and do not expire, but are only valid for the list and filters that produced them.
sortOrdering: name, revision or updated_at, each with an optional :asc/:desc suffix (default name:asc). An unknown value is rejected. Cursors are bound to the ordering that issued them, so changing sort mid-walk needs a fresh first page. The rules summary and the used-by count are not orderable: the first is rendered from the rule tree and the second is a per-row count over promotions, neither being a column of audiences.
searchCase-insensitive match on name or description. Applied inside the keyset predicate, so paging a filtered list stays consistent.
presets_onlyReturn only audiences an operator authored, dropping the row each targeted promotion owns. Applied inside the keyset predicate, so paging a filtered list stays consistent.
purposeReturn only audiences marked for this surface. Applied inside the keyset predicate, so paging a filtered list stays consistent. An unrecognised value is rejected rather than answered with an empty page.
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
List audiences › Responses
OK
Create an audience
Creates a saved audience at revision 1. An empty rule set is refused rather than interpreted: set match_all to target everyone, or supply a root rule group. A name already used in this workspace comes back as a field error on name.
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Create an audience › Request Body
The rule set. An empty tree is REFUSED rather than interpreted: the two targeting systems that predate this domain read an empty selector as "everyone" and as "nobody" respectively, and the difference between those readings is the entire customer base — so targeting everyone is something the operator states, with match_all.
nameOperator-facing name. Must be unique within the workspace; a taken name is refused as a field error on name, not as a bare conflict.
descriptionWhat this population is for. Optional.
purposesWhich surfaces may point at this audience. OMIT to allow all five, which is what every audience created before this field existed allows. An empty array is refused: an audience marked for nothing could not be used anywhere.
Create an audience › Responses
Created
Preview an audience definition
Counts a rule set and returns a bounded sample of the customers it matches. Takes the definition itself rather than an audience id, so unsaved editor state can be previewed. The counts are a ladder — matched, then mailable, then sendable — taken in one statement so the rungs cannot disagree; a rung this endpoint cannot measure is returned as null rather than as a repeat of the one above it.
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Preview an audience definition › Request Body
The rule set to count and sample. Taken by VALUE and not by id, so the builder can preview unsaved editor state.
limitHow many matching customers to sample. Default 25. The counts are exact regardless of this bound — it caps the sample, never the arithmetic.
Preview an audience definition › Responses
OK
Get an audience
Returns one audience and its full rule tree.
path Parameters
idAudience UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Get an audience › Responses
OK
Delete an audience
Soft-deletes the audience. REFUSED WITH 409 while anything still points at it, naming what does: promotions, emails narrowed to it, scheduled changes scoped to it, and the settings that target it (the e-invoice rollout). A cascade was never an option, because deleting an audience out from under a live promotion would silently retarget it. Repoint or delete those first; GET /audiences/{id}/usage lists all four kinds.
path Parameters
idAudience UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Delete an audience › Responses
No Content
Rename an audience
Changes the audience's name and description. It never bumps the revision, because nothing about who the audience matches has changed. Both naming fields are replaced: an omitted description clears it.
path Parameters
idAudience UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Rename an audience › Request Body
nameNew operator-facing name.
descriptionNew description. ABSENT MEANS EMPTY: this endpoint replaces both naming fields, it does not merge them.
Rename an audience › Responses
OK
Ask whether one customer is in an audience
Answers membership for a SINGLE customer, directly — the question a screen asks beside one customer, rather than a count of a narrowed definition. THREE ANSWERS: member true, member false, or member null when the customer id names no live customer of this organization (a deleted customer is null, never false, because the audience predicate excludes deleted rows and reporting that as an exclusion would be a decision about somebody who is not there). A deleted or unknown AUDIENCE is 404. The rules are read server-side and the revision that answered comes back with the answer, so the result describes the audience as it is now rather than as the caller last saw it.
path Parameters
idAudience UUID
query Parameters
customer_idThe customer to ask about.
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Ask whether one customer is in an audience › Responses
OK
Set which surfaces may use an audience
Replaces the set of surfaces allowed to point at this audience: email (both mail tiers), promotion, schedule (a scheduled change's scope), rollout (the e-invoice rollout target) and documents (a document-template block gated on the recipient). At least one is required — an audience marked for nothing could not be used anywhere. It never bumps the revision, because where an audience may be used says nothing about whom it matches. ADDING a purpose always succeeds. REMOVING one that a live reference still needs is REFUSED WITH 409, naming the emails, changes or settings that hold it — the same answer, the same words and the same next step as a refused delete: go un-point those things first. Enforcement is real for email, schedule, rollout and documents, which all point at an audience by id. It is NOT enforced for promotion: a promotion copies an audience's rules in the browser and never sends an audience id, so no server-side write knows which library audience was copied — there the value filters the preset picker and guards nothing.
path Parameters
idAudience UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Set which surfaces may use an audience › Request Body
purposesThe replacement set. At least one. Case-insensitive, de-duplicated and stored in a fixed order, so the response is the canonical form rather than what was sent. ADDING a purpose always succeeds; REMOVING one that a live reference still needs is refused with 409 naming the rows, exactly as a delete is.
Set which surfaces may use an audience › Responses
OK
List an audience's rule history
Returns the append-only history of what this audience's rules said, newest first, cursor-paginated (default 50, max 200 per page). Every fan-out and enrollment records the audience id and revision on its durable event, so this is how "who was targeted when that fired" is answered — and because that question is about an OLD revision, the whole history is walkable rather than capped. Ordered by the audience's own revision counter, not by timestamp; ?sort= accepts revision with an optional :asc/:desc suffix.
path Parameters
idAudience UUID
query Parameters
limitPage size. Values above the server-side cap are clamped (standard default 50, cap 200; a few document-heavy lists use larger windows). Invalid values fall back to the default.
cursorOpaque continuation token from the previous response's pagination.cursor. Omit for the first page. Cursors are stateless and do not expire, but are only valid for the list and filters that produced them.
sortOrdering: revision, with an optional :asc/:desc suffix (default revision:desc). The key is the audience's own revision counter, not a timestamp. An unknown value is rejected. Cursors are bound to the ordering that issued them, so changing sort mid-walk needs a fresh first page.
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
List an audience's rule history › Responses
OK
Replace an audience's rules
Replaces the rule tree and appends a revision. A write whose canonical content hash equals the stored one is a no-op — no new revision, no bump, the audience returned unchanged — so saving an unchanged tree, or re-typing "de" as "DE", costs the operator nothing. Any write that does move the population bumps the revision, which is what a broadcast re-fire confirm is checked against.
path Parameters
idAudience UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Replace an audience's rules › Request Body
The replacement rule set. A write whose canonical content hash equals the stored one is a NO-OP: no new revision row, no bump, the audience returned unchanged — so the editor may save freely without costing the operator a spurious refused re-fire.
Replace an audience's rules › Responses
OK
Get what points at an audience
Returns everything currently referencing this audience — the blast radius of a delete. Four kinds: promotions, emails narrowed to it, scheduled changes that have not run yet, and settings whose value is this audience id. Empty means the audience can be deleted; anything listed here is what a DELETE would be refused for, and what removing the matching purpose would be refused for. Fetch it when a destructive confirm is pending rather than as a list column: it is one request per audience.
path Parameters
idAudience UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Get what points at an audience › Responses
OK