Extole Audiences API

openapi: 3.0.1
info:
  description: 'Consumer-to-Extole integration endpoints: consumer event submission, zone rendering, profile management, and SDK-backing operations for browser and native app environments.'
  title: Integration API - Consumer to Extole Audiences API
  version: '1.0'
servers:
- description: Production
  url: https://{brand}.extole.io
  variables:
    brand:
      default: yourcompany
      description: Your Extole client subdomain (e.g. 'mycompany' for mycompany.extole.io)
security:
- HEADER: []
- QUERY: []
- COOKIE: []
tags:
- name: Audiences
paths:
  /v1/audiences:
    get:
      description: 'Returns the client''s audience definitions sorted by creation date, newest first. By default archived audiences are excluded; pass `include_archived=true` to include them. Use `limit` and `offset` to page (defaults: `limit=1000`, `offset=0`). Each entry is the editable definition - for runtime targeting reads, use `GET /v1/audiences/built` instead.'
      operationId: listAudiences
      parameters:
      - in: query
        name: include_archived
        schema:
          type: boolean
      - in: query
        name: limit
        schema:
          format: int32
          type: integer
      - in: query
        name: offset
        schema:
          format: int32
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/AudienceResponse'
                type: array
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                binding_error:
                  $ref: '#/components/examples/binding_error'
                invalid_json:
                  $ref: '#/components/examples/invalid_json'
                invalid_parameter:
                  $ref: '#/components/examples/invalid_parameter'
                missing_request_body:
                  $ref: '#/components/examples/missing_request_body'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: List audiences
      tags:
      - Audiences
      x-extole-bundle: management
      x-extole-visibility: visible
    post:
      description: Creates a new audience definition. `name` is required; `enabled`, `tags`, and `component_references` are optional. New audiences default to enabled. Tags must be 255 characters or fewer each; the resolved name must also be 255 characters or fewer. Returns the created audience.
      operationId: createAudience
      requestBody:
        content:
          application/json:
            example:
              component_ids:
              - component_id
              component_references:
              - component_id: component_id
                socket_names:
                - socket_name
              enabled: true
              name: name
              tags:
              - tag
            schema:
              $ref: '#/components/schemas/AudienceCreateRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AudienceResponse'
          description: Created audience.
        '400':
          content:
            application/json:
              examples:
                invalid_audience_tag:
                  $ref: '#/components/examples/invalid_audience_tag'
                invalid_component_reference:
                  $ref: '#/components/examples/invalid_component_reference'
                missing_audience_name:
                  $ref: '#/components/examples/missing_audience_name'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Bad request. The named examples below cover the validation errors that are specific to this operation. Other 400 causes include malformed JSON, an empty request body, and an invalid `Time-Zone` header - inspect the response `code` field for the specific error.
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: Create audience
      tags:
      - Audiences
      x-extole-bundle: management
      x-extole-visibility: visible
  /v1/audiences/built:
    get:
      description: 'Returns the rendered (built) audience snapshots that the runtime evaluates against - the resolved name, enabled flag, tags, and component references for every audience the client owns. Filter by `name` (supports a trailing `*` wildcard), by `enabled` (`ENABLED`, `DISABLED`, or `ANY`), and by archived status. Use `limit` and `offset` to page (defaults: `limit=1000`, `offset=0`). Use `GET /v1/audiences` for the editable definitions.'
      operationId: listBuiltAudiences
      parameters:
      - in: query
        name: name
        schema:
          type: string
      - in: query
        name: include_archived
        schema:
          type: boolean
      - in: query
        name: enabled
        schema:
          description: Filter applied by `GET /v1/audiences/built?enabled=...`. `ENABLED` returns only audiences whose enabled flag resolves to `true`, `DISABLED` only those that resolve to `false`, and `ANY` returns both.
          enum:
          - ANY
          - DISABLED
          - ENABLED
          type: string
      - in: query
        name: limit
        schema:
          format: int32
          type: integer
      - in: query
        name: offset
        schema:
          format: int32
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/BuiltAudienceResponse'
                type: array
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                binding_error:
                  $ref: '#/components/examples/binding_error'
                invalid_json:
                  $ref: '#/components/examples/invalid_json'
                invalid_parameter:
                  $ref: '#/components/examples/invalid_parameter'
                missing_request_body:
                  $ref: '#/components/examples/missing_request_body'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: List built audiences
      tags:
      - Audiences
      x-extole-bundle: management
      x-extole-visibility: visible
  /v1/audiences/{audience_id}:
    get:
      description: Returns the editable audience definition for the supplied `audience_id`, including its name, enabled state, tags, and the campaign components that reference it. For the rendered (runtime) snapshot use `GET /v1/audiences/{audience_id}/built` instead.
      operationId: getAudience
      parameters:
      - in: path
        name: audience_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AudienceResponse'
          description: Audience definition.
        '400':
          content:
            application/json:
              examples:
                audience_not_found:
                  $ref: '#/components/examples/audience_not_found'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: The supplied `audience_id` does not match an existing audience for this client. Inspect the response `code` field for the specific error.
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: Get audience
      tags:
      - Audiences
      x-extole-bundle: management
      x-extole-visibility: visible
    put:
      description: Updates an existing audience. Only fields supplied in the body are changed; omitted fields are left untouched. Sending `null` for `name` returns `400 invalid_null` because `name` is a required attribute on the audience. Returns the updated audience.
      operationId: updateAudience
      parameters:
      - in: path
        name: audience_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              component_ids:
              - component_id
              component_references:
              - component_id: component_id
                socket_names:
                - socket_name
              enabled: true
              name: name
              tags:
              - tag
            schema:
              $ref: '#/components/schemas/AudienceUpdateRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AudienceResponse'
          description: Updated audience.
        '400':
          content:
            application/json:
              examples:
                audience_not_found:
                  $ref: '#/components/examples/audience_not_found'
                invalid_audience_name:
                  $ref: '#/components/examples/invalid_audience_name'
                invalid_audience_tag:
                  $ref: '#/components/examples/invalid_audience_tag'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Bad request. The named examples below cover the validation errors that are specific to this operation. Other 400 causes include malformed JSON, an empty request body, and an invalid `Time-Zone` header - inspect the response `code` field for the specific error.
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: Update audience
      tags:
      - Audiences
      x-extole-bundle: management
      x-extole-visibility: visible
    delete:
      description: Soft-archives the audience. Archived audiences disappear from default `GET /v1/audiences` and `GET /v1/audiences/built` responses; pass `include_archived=true` to surface them. Reversible via `POST /v1/audiences/{audience_id}/unarchive`. Fails if the audience is still referenced by a campaign-controller membership trigger, a create- or remove-membership controller action, or a campaign component variable.
      operationId: archiveAudience
      parameters:
      - in: path
        name: audience_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AudienceResponse'
          description: Archived audience.
        '400':
          content:
            application/json:
              examples:
                audience_associated_with_audience_membership_controller_trigger:
                  $ref: '#/components/examples/audience_associated_with_audience_membership_controller_trigger'
                audience_associated_with_component_variable:
                  $ref: '#/components/examples/audience_associated_with_component_variable'
                audience_associated_with_create_membership_controller_action:
                  $ref: '#/components/examples/audience_associated_with_create_membership_controller_action'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: 'Bad request. The named examples below cover the most common reasons an audience cannot be archived, deleted, or unarchived: it is still referenced by a campaign-controller membership trigger, by a create-/remove-membership controller action, or by a campaign component variable. The audience must be detached from those references before the lifecycle operation can succeed. The full set of association codes is auto-derived; inspect the response `code` field for the specific error.'
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: Archive audience
      tags:
      - Audiences
      x-extole-bundle: management
      x-extole-visibility: visible
  /v1/audiences/{audience_id}/built:
    get:
      description: Returns the rendered (built) snapshot for the supplied `audience_id`. The snapshot has the same shape as `GET /v1/audiences/{audience_id}/built` items in the list response and is what the runtime evaluates against during targeting.
      operationId: getBuiltAudience
      parameters:
      - in: path
        name: audience_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuiltAudienceResponse'
          description: Built audience snapshot.
        '400':
          content:
            application/json:
              examples:
                audience_not_found:
                  $ref: '#/components/examples/audience_not_found'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: The supplied `audience_id` does not match an existing audience for this client. Inspect the response `code` field for the specific error.
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: Get built audience
      tags:
      - Audiences
      x-extole-bundle: management
      x-extole-visibility: visible
  /v1/audiences/{audience_id}/members:
    get:
      description: Returns the person IDs of all current members of the specified audience.
      operationId: listAudienceMemberIds
      parameters:
      - in: path
        name: audience_id
        required: true
        schema:
          type: string
      - in: query
        name: email
        schema:
          type: string
      - in: query
        name: sort_order
        schema:
          type: string
      - in: query
        name: limit
        schema:
          format: int32
          type: integer
      - in: query
        name: offset
        schema:
          format: int32
          type: integer
      - in: query
        name: has_data_attributes
        schema:
          items:
            type: string
          type: array
      - in: query
        name: include_data_attributes
        schema:
          items:
            type: string
          type: array
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  type: string
                type: array
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                audience_not_found:
                  $ref: '#/components/examples/audience_not_found'
                binding_error:
                  $ref: '#/components/examples/binding_error'
                invalid_json:
                  $ref: '#/components/examples/invalid_json'
                invalid_parameter:
                  $ref: '#/components/examples/invalid_parameter'
                invalid_query_limit:
                  $ref: '#/components/examples/invalid_query_limit'
                missing_request_body:
                  $ref: '#/components/examples/missing_request_body'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Forbidden
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: List audience member IDs
      tags:
      - Audiences
      x-extole-bundle: management
      x-extole-visibility: visible
  /v1/audiences/{audience_id}/members/download{format}:
    get:
      description: Downloads the full member list for the specified audience. Append a format extension (`.csv`, `.json`, `.xlsx`) to select the download format.
      operationId: downloadAudienceMembers
      parameters:
      - in: path
        name: audience_id
        required: true
        schema:
          type: string
      - in: header
        name: Content-Type
        schema:
          nullable: true
          type: string
      - in: path
        name: format
        required: true
        schema:
          nullable: true
          pattern: (\.csv|\.json|\.xlsx)?
          type: string
      - in: query
        name: filename
        schema:
          type: string
      - in: query
        name: sort_order
        schema:
          type: string
      - in: query
        name: limit
        schema:
          format: int32
          type: integer
      - in: query
        name: offset
        schema:
          format: int32
          type: integer
      responses:
        '200':
          content:
            '*/*': {}
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                audience_member_list_content_type_not_supported:
                  $ref: '#/components/examples/audience_member_list_content_type_not_supported'
                audience_member_list_format_not_supported:
                  $ref: '#/components/examples/audience_member_list_format_not_supported'
                audience_not_found:
                  $ref: '#/components/examples/audience_not_found'
                binding_error:
                  $ref: '#/components/examples/binding_error'
                invalid_json:
                  $ref: '#/components/examples/invalid_json'
                invalid_parameter:
                  $ref: '#/components/examples/invalid_parameter'
                invalid_query_limit:
                  $ref: '#/components/examples/invalid_query_limit'
                missing_request_body:
                  $ref: '#/components/examples/missing_request_body'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              examples:
                payment_required:
                  $ref: '#/components/examples/payment_required'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              example

# --- truncated at 32 KB (129 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/extole/refs/heads/main/openapi/extole-audiences-api-openapi.yml