Audiences

Audiences use the /segments resource. Reading lists or details requires segments:read; mutations require segments:write and Idempotency-Key.

Choose a type

POST /segments creates an explicit assignment audience:

{"name": "Store customers", "type": "assignment"}

Or one based on profile conditions:

{
  "name": "Spanish contacts",
  "type": "conditions",
  "definition": {
    "schemaVersion": 1,
    "rule": {
      "kind": "field",
      "field": {"scope": "custom", "id": "locale", "type": "text"},
      "operator": "eq",
      "value": "es-CR"
    }
  }
}

The type remains fixed. POST /segments/{id}/save saves configuration with If-Match; the authoritative revision is ruleRevision.

Assign contacts or define rules

For assignment, use PUT /segments/{id}/contacts/{contactId} and DELETE on the same route with an empty body or {}. POST /segments/{id}/assign with {contactId} is also available. Repeating an addition does not create another transition.

For conditions, combine rules with {kind: "group", operator: "and" | "or", children: [...]}. Each field accepts operators for its type. Custom fields use {scope: "custom", id, type}; membership conditions use kind: "segment", segmentId and member_of or not_member_of, referencing assignment audiences only.

Missing values only match is_not_set; they are distinct from false, zero and empty arrays. Profile or assignment changes reconcile calculated membership; do not manually write members to condition audiences.

Evaluate before a broadcast

POST /segments/{id}/evaluate creates asynchronous work and returns 202 with a generation receipt. A complete generation of the current revision can become activeGenerationId. The key API exposes neither member lists nor generation polling; inspect results in Marketing.

A generation is not a global snapshot while contacts change. Broadcasts pin a complete generation, and each send checks consent and eligibility again.

Archive with a revision

archive, restore and DELETE /segments/{id} require a revision. Dependencies can block archive or deletion; restoring checks capacity. Plan limits may be lower than the operational ceiling of 50 active audiences. See Marketing audiences.