Extole Domains 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 Domains 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: Domains
paths:
  /v1/client-domain-patterns:
    get:
      description: Returns all domain pattern definitions for the calling client. Domain patterns define which URL patterns the Extole platform recognises as belonging to this client — they control campaign-tracking domain matching, shareable link generation, and zone-rendering domain allow-listing. Each entry includes its `pattern`, `type` (`GLOB`, `DOMAIN`, or `SUB_DOMAIN`), and the optional `client_domain_id` that links it to a specific program domain configuration.
      operationId: listClientDomainPatterns
      parameters:
      - in: query
        name: client_domain_id
        schema:
          type: string
      - 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/ClientDomainPatternResponse'
                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 client domain patterns
      tags:
      - Domains
      x-extole-bundle: management-expert
      x-extole-visibility: visible
    post:
      description: Creates a new domain pattern definition and returns the persisted record with its server-assigned id. The `pattern` field is required. `type` defaults to `GLOB` when omitted. Set `test=true` to create a test-only pattern that is not used in production domain matching. The pattern must be buildable; complex `BuildtimeEvaluatable` expressions are evaluated at build time.
      operationId: createClientDomainPattern
      requestBody:
        content:
          application/json:
            example:
              client_domain_id: client_domain_id
              component_ids:
              - component_id
              component_references:
              - component_id: component_id
                socket_names:
                - socket_name
              pattern: pattern
              test: true
              type: DOMAIN
            schema:
              $ref: '#/components/schemas/ClientDomainPatternCreateRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientDomainPatternResponse'
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                binding_error:
                  $ref: '#/components/examples/binding_error'
                campaign_component_absolute_name_missing:
                  $ref: '#/components/examples/campaign_component_absolute_name_missing'
                campaign_component_description_out_of_range:
                  $ref: '#/components/examples/campaign_component_description_out_of_range'
                campaign_component_display_name_contains_illegal_character:
                  $ref: '#/components/examples/campaign_component_display_name_contains_illegal_character'
                campaign_component_display_name_out_of_range:
                  $ref: '#/components/examples/campaign_component_display_name_out_of_range'
                campaign_component_id_missing:
                  $ref: '#/components/examples/campaign_component_id_missing'
                campaign_component_name_already_in_use:
                  $ref: '#/components/examples/campaign_component_name_already_in_use'
                campaign_component_name_contains_illegal_character:
                  $ref: '#/components/examples/campaign_component_name_contains_illegal_character'
                campaign_component_name_out_of_range:
                  $ref: '#/components/examples/campaign_component_name_out_of_range'
                campaign_component_type_validation_failed:
                  $ref: '#/components/examples/campaign_component_type_validation_failed'
                circular_component_reference:
                  $ref: '#/components/examples/circular_component_reference'
                client_domain_pattern_build_failed:
                  $ref: '#/components/examples/client_domain_pattern_build_failed'
                component_facets_not_found:
                  $ref: '#/components/examples/component_facets_not_found'
                excessive_component_reference:
                  $ref: '#/components/examples/excessive_component_reference'
                external_element_is_referenced_by_active_configuration:
                  $ref: '#/components/examples/external_element_is_referenced_by_active_configuration'
                external_elements_cannot_have_multiple_references:
                  $ref: '#/components/examples/external_elements_cannot_have_multiple_references'
                invalid_client_domain_pattern_domain:
                  $ref: '#/components/examples/invalid_client_domain_pattern_domain'
                invalid_client_domain_pattern_syntax:
                  $ref: '#/components/examples/invalid_client_domain_pattern_syntax'
                invalid_component_installed_into_socket:
                  $ref: '#/components/examples/invalid_component_installed_into_socket'
                invalid_component_reference:
                  $ref: '#/components/examples/invalid_component_reference'
                invalid_component_reference_socket_name:
                  $ref: '#/components/examples/invalid_component_reference_socket_name'
                invalid_external_component_reference:
                  $ref: '#/components/examples/invalid_external_component_reference'
                invalid_json:
                  $ref: '#/components/examples/invalid_json'
                invalid_parameter:
                  $ref: '#/components/examples/invalid_parameter'
                missing_client_domain_pattern:
                  $ref: '#/components/examples/missing_client_domain_pattern'
                missing_request_body:
                  $ref: '#/components/examples/missing_request_body'
                orphan_external_component_reference:
                  $ref: '#/components/examples/orphan_external_component_reference'
                redundant_component_reference:
                  $ref: '#/components/examples/redundant_component_reference'
                self_component_reference:
                  $ref: '#/components/examples/self_component_reference'
              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: Create client domain pattern
      tags:
      - Domains
      x-extole-bundle: management-expert
      x-extole-visibility: visible
  /v1/client-domain-patterns/built:
    get:
      description: Returns all domain patterns in their fully evaluated (built) runtime form, with all `BuildtimeEvaluatable` fields resolved to their current string values. Use this when the calling system needs the effective pattern expressions rather than the source template definitions. Use `GET /v1/client-domain-patterns` for the editable source definitions.
      operationId: listBuiltClientDomainPatterns
      parameters:
      - in: query
        name: client_domain_id
        schema:
          type: string
      - 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/BuiltClientDomainPatternResponse'
                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 client domain patterns
      tags:
      - Domains
      x-extole-bundle: management-expert
      x-extole-visibility: visible
  /v1/client-domain-patterns/{id}:
    get:
      description: Returns the source definition for the supplied domain pattern, including its `pattern` expression, `type`, optional `client_domain_id`, and `test` flag. Returns `400 client_domain_pattern_not_found` if the id does not exist or is not accessible to the calling client. For the compiled runtime snapshot use `GET /v1/client-domain-patterns/{id}/built` instead.
      operationId: getClientDomainPattern
      parameters:
      - description: Identifier of the client domain pattern to retrieve.
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientDomainPatternResponse'
          description: Client domain pattern source definition with its build-time pattern expression, domain type, and component references.
        '400':
          content:
            application/json:
              examples:
                client_domain_pattern_not_found:
                  $ref: '#/components/examples/client_domain_pattern_not_found'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: The supplied `id` does not match an existing domain pattern 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 client domain pattern
      tags:
      - Domains
      x-extole-bundle: management-expert
      x-extole-visibility: visible
    put:
      description: Applies a partial update to the supplied domain pattern. Only the fields present in the body are changed; omitted fields are left intact. Returns the updated pattern record on success. Returns `400 client_domain_pattern_not_found` if the id does not exist.
      operationId: updateClientDomainPattern
      parameters:
      - description: Identifier of the client domain pattern to update.
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              client_domain_id: {}
              component_ids:
              - component_id
              component_references:
              - component_id: component_id
                socket_names:
                - socket_name
              pattern: pattern
              test: true
              type: DOMAIN
            schema:
              $ref: '#/components/schemas/ClientDomainPatternUpdateRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientDomainPatternResponse'
          description: Client domain pattern source definition with its build-time pattern expression, domain type, and component references.
        '400':
          content:
            application/json:
              examples:
                client_domain_pattern_not_found:
                  $ref: '#/components/examples/client_domain_pattern_not_found'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: The supplied `id` does not match an existing domain pattern 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: Update client domain pattern
      tags:
      - Domains
      x-extole-bundle: management-expert
      x-extole-visibility: visible
    delete:
      description: Soft-archives the supplied domain pattern. Archived patterns are retained but are no longer used in domain matching. Reversible via `POST /v1/client-domain-patterns/{id}/unarchive`. Returns the updated pattern record. Returns `400 client_domain_pattern_not_found` if the id does not exist.
      operationId: archiveClientDomainPattern
      parameters:
      - description: Identifier of the client domain pattern to archive.
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientDomainPatternResponse'
          description: Archived client domain pattern source definition.
        '400':
          content:
            application/json:
              examples:
                client_domain_pattern_not_found:
                  $ref: '#/components/examples/client_domain_pattern_not_found'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: The supplied `id` does not match an existing domain pattern 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: Archive client domain pattern
      tags:
      - Domains
      x-extole-bundle: management-expert
      x-extole-visibility: visible
  /v1/client-domain-patterns/{id}/built:
    get:
      description: Returns the fully evaluated (built) runtime form for the supplied domain pattern, with all `BuildtimeEvaluatable` fields resolved. Returns `400 client_domain_pattern_not_found` if the id does not exist or is not accessible to the calling client.
      operationId: getBuiltClientDomainPattern
      parameters:
      - description: Identifier of the client domain pattern to retrieve in built form.
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuiltClientDomainPatternResponse'
          description: Built client domain pattern with evaluated runtime values used for domain matching.
        '400':
          content:
            application/json:
              examples:
                client_domain_pattern_not_found:
                  $ref: '#/components/examples/client_domain_pattern_not_found'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: The supplied `id` does not match an existing domain pattern 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 client domain pattern
      tags:
      - Domains
      x-extole-bundle: management-expert
      x-extole-visibility: visible
  /v1/client-domain-patterns/{id}/delete:
    post:
      description: Hard-deletes the supplied domain pattern. Unlike archiving, deletion is irreversible. Returns the deleted pattern record on success. Returns `400 client_domain_pattern_not_found` if the id does not exist.
      operationId: deleteClientDomainPattern
      parameters:
      - description: Identifier of the client domain pattern to delete.
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientDomainPatternResponse'
          description: Deleted client domain pattern source definition.
        '400':
          content:
            application/json:
              examples:
                client_domain_pattern_not_found:
                  $ref: '#/components/examples/client_domain_pattern_not_found'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: The supplied `id` does not match an existing domain pattern 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: Delete client domain pattern
      tags:
      - Domains
      x-extole-bundle: management-expert
      x-extole-visibility: visible
  /v1/client-domain-patterns/{id}/unarchive:
    post:
      description: Restores a previously archived domain pattern so it is active in domain matching again. Returns the restored pattern record. Returns `400 client_domain_pattern_not_found` if the id does not exist.
      operationId: unarchiveClientDomainPattern
      parameters:
      - description: Identifier of the client domain pattern to unarchive.
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
     

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