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 Events 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: Events
paths:
  /events/{event_name}:
    get:
      description: Fires the named consumer event using data from the query string and optional JWT claim. Always returns HTTP 200 regardless of outcome — check for an `X-Extole-Error-Message` response header to detect processing errors. A new `access_token` cookie may be set on the response when the event establishes or upgrades a consumer identity.
      operationId: fetchConsumerEventByName
      parameters:
      - in: path
        name: event_name
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitEventResponse'
          description: 'Always return 200. Strongly typed response body, see SubmitEventResponse. '
          headers:
            X-Extole-Cookie-Consent:
              schema:
                type: string
              style: simple
            X-Extole-Token:
              schema:
                type: string
              style: simple
        '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
        '403':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              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: Submit a consumer event by URL
      tags:
      - Events
      x-extole-bundle: integration-consumer-to-extole
      x-extole-visibility: visible
  /v6/async-events:
    post:
      description: Submits a consumer event asynchronously. No per-request rate limit - use for high-volume or bulk integrations. May return 429 only if the downstream ingestion queue is saturated. Only `event_id` is returned; person identification occurs asynchronously after the request returns.
      operationId: submitEventAsync
      requestBody:
        content:
          application/json:
            example:
              data:
                email: user@example.com
                event_time: '2024-01-15T12:00:00Z'
                partner_user_id: usr_8392047156
                person_id: 7465313346145957284
              event_name: event_name
              event_time: event_time
            schema:
              $ref: '#/components/schemas/EventDispatcherRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventDispatcherAsyncResponse'
          description: Event accepted and queued for asynchronous processing. Returns the assigned `event_id`. Person identification completes after the response is returned.
        '400':
          content:
            application/json:
              examples:
                event_blocked:
                  $ref: '#/components/examples/event_blocked'
                invalid_event_time_format:
                  $ref: '#/components/examples/invalid_event_time_format'
                missing_event_name:
                  $ref: '#/components/examples/missing_event_name'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Bad request. The named examples below cover this operation's specific validation errors. Other 400 causes include malformed JSON, an invalid `Time-Zone` header, and an empty request body - 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
      servers:
      - description: Production
        url: https://events.extole.io
      summary: Submit an event asynchronously
      tags:
      - Events
      x-extole-bundle: integration-server-to-extole
      x-extole-visibility: visible
  /v6/async-events/{event_name}:
    post:
      description: Submits a specific named consumer event asynchronously. The event name is supplied in the URL path and the body is an open data map. No per-request rate limit. Returns `event_id` only; person identification occurs asynchronously.
      operationId: submitNamedEventAsync
      parameters:
      - in: path
        name: event_name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              email: user@example.com
              event_time: '2024-01-15T12:00:00Z'
              partner_user_id: usr_8392047156
              person_id: 7465313346145957284
            schema:
              $ref: '#/components/schemas/EventSubmissionData'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventDispatcherAsyncResponse'
          description: Event accepted and queued for asynchronous processing. Returns the assigned `event_id`. Person identification completes after the response is returned.
        '400':
          content:
            application/json:
              examples:
                event_blocked:
                  $ref: '#/components/examples/event_blocked'
                invalid_event_time_format:
                  $ref: '#/components/examples/invalid_event_time_format'
                missing_event_name:
                  $ref: '#/components/examples/missing_event_name'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Bad request. The named examples below cover this operation's specific validation errors. Other 400 causes include malformed JSON, an invalid `Time-Zone` header, and an empty request body - 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
      servers:
      - description: Production
        url: https://events.extole.io
      summary: Submit a named event asynchronously
      tags:
      - Events
      x-extole-bundle: integration-server-to-extole
      x-extole-visibility: visible
  /v6/events:
    post:
      description: Submits a consumer event synchronously. Returns both `event_id` and `person_id`. Use when you need immediate confirmation that the event was processed and identity resolution has completed. For high-volume ingestion use `POST /v6/async-events` instead.
      operationId: submitEvent
      requestBody:
        content:
          application/json:
            example:
              data:
                email: user@example.com
                event_time: '2024-01-15T12:00:00Z'
                partner_user_id: usr_8392047156
                person_id: 7465313346145957284
              event_name: event_name
              event_time: event_time
            schema:
              $ref: '#/components/schemas/EventDispatcherRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventDispatcherResponse'
          description: Event accepted and processed. Returns the assigned `event_id` and the resolved Extole `person_id`.
        '400':
          content:
            application/json:
              examples:
                event_blocked:
                  $ref: '#/components/examples/event_blocked'
                invalid_event_time_format:
                  $ref: '#/components/examples/invalid_event_time_format'
                missing_event_name:
                  $ref: '#/components/examples/missing_event_name'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Bad request. The named examples below cover this operation's specific validation errors. Other 400 causes include malformed JSON, an invalid `Time-Zone` header, and an empty request body - 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
      servers:
      - description: Production
        url: https://events.extole.io
      summary: Submit an event
      tags:
      - Events
      x-extole-bundle: integration-server-to-extole
      x-extole-visibility: visible
  /v6/events/{event_name}:
    post:
      description: Submits a specific named consumer event synchronously. The event name is supplied in the URL path rather than in the request body, and the body is an open data map.
      operationId: submitNamedEvent
      parameters:
      - in: path
        name: event_name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              email: user@example.com
              event_time: '2024-01-15T12:00:00Z'
              partner_user_id: usr_8392047156
              person_id: 7465313346145957284
            schema:
              $ref: '#/components/schemas/EventSubmissionData'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventDispatcherResponse'
          description: Event accepted and processed. Returns the assigned `event_id` and the resolved Extole `person_id`.
        '400':
          content:
            application/json:
              examples:
                event_blocked:
                  $ref: '#/components/examples/event_blocked'
                invalid_event_time_format:
                  $ref: '#/components/examples/invalid_event_time_format'
                missing_event_name:
                  $ref: '#/components/examples/missing_event_name'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Bad request. The named examples below cover this operation's specific validation errors. Other 400 causes include malformed JSON, an invalid `Time-Zone` header, and an empty request body - 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
      servers:
      - description: Production
        url: https://events.extole.io
      summary: Submit a named event
      tags:
      - Events
      x-extole-bundle: integration-server-to-extole
      x-extole-visibility: visible
  /v3/signals/step/status/{pollingId}:
    get:
      operationId: getStatus_2
      parameters:
      - in: path
        name: pollingId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StepSignalResponse'
          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
        '403':
          content:
            application/json:
              examples:
                access_denied:
                  $ref: '#/components/examples/access_denied'
                expired_access_token:
                  $ref: '#/components/examples/expired_access_token'
                invalid_access_token:
                  $ref: '#/components/examples/invalid_access_token'
                jwt_authentication_error:
                  $ref: '#/components/examples/jwt_authentication_error'
                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
      tags:
      - Events
      x-extole-bundle: integration-consumer-to-extole
      x-extole-visibility: expert
components:
  examples:
    invalid_json:
      summary: invalid_json
      value:
        code: invalid_json
        http_status_code: 400
        message: JSON is invalid
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    expired_access_token:
      summary: expired_access_token
      value:
        code: expired_access_token
        http_status_code: 403
        message: The access_token provided with this request has expired.
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    invalid_event_time_format:
      summary: invalid_event_time_format
      value:
        code: invalid_event_time_format
        http_status_code: 400
        message: 'Invalid event time format. Expected: ISO8601 format'
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    payment_required:
      summary: payment_required
      value:
        code: payment_required
        http_status_code: 402
        message: The access_token provided is associated with an unpaid account.
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    missing_access_token:
      summary: missing_access_token
      value:
        code: missing_access_token
        http_status_code: 403
        message: No access_token was provided with this request.
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    event_blocked:
      summary: event_blocked
      value:
        code: event_blocked
        http_status_code: 400
        message: Blocked due to client specific rules to ignore spurious events
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    jwt_authentication_error:
      summary: jwt_authentication_error
      value:
        code: jwt_authentication_error
        http_status_code: 403
        message: The jwt authentication failed.
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    unsupported_media_type:
      summary: unsupported_media_type
      value:
        code: unsupported_media_type
        http_status_code: 415
        message: Request had an unsupported or no media type
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    method_unauthorized:
      summary: method_unauthorized
      value:
        code: method_unauthorized
        http_status_code: 401
        message: Unauthorized access to this endpoint
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    invalid_access_token:
      summary: invalid_access_token
      value:
        code: invalid_access_token
        http_status_code: 403
        message: The access_token provided with this request is invalid.
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    missing_request_body:
      summary: missing_request_body
      value:
        code: missing_request_body
        http_status_code: 400
        message: Missing request body
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    binding_error:
      summary: binding_error
      value:
        code: binding_error
        http_status_code: 400
        message: Argument is not of the expected type
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    access_denied:
      summary: access_denied
      value:
        code: access_denied
        http_status_code: 403
        message: The access_token provided is not permitted to access the specified resource.
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    too_many_requests:
      summary: too_many_requests
      value:
        code: too_many_requests
        http_status_code: 429
        message: The server is unable to process your request at the moment, please retry later.
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    invalid_parameter:
      summary: invalid_parameter
      value:
        code: invalid_parameter
        http_status_code: 400
        message: Parameter is invalid.
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    missing_event_name:
      summary: missing_event_name
      value:
        code: missing_event_name
        http_status_code: 400
        message: Event name is required.
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
  schemas:
    QualityRuleResult:
      properties:
        rule_name:
          type: string
        score:
          enum:
          - ERROR
          - HIGH
          - LOW
          type: string
      type: object
    StepSignalResponse:
      properties:
        polling_id:
          type: string
        signals:
          items:
            $ref: '#/components/schemas/StepSignal'
          type: array
      required:
      - polling_id
      - signals
      type: object
    SubmitEventResponse:
      properties:
        cookie_consent:
          description: Cookie consent string set by the platform during event processing. Null when no consent update occurred.
          nullable: true
          type: string
        id:
          description: Extole-assigned event identifier for the fired event.
          readOnly: true
          type: string
        token:
          description: Current access token for the consumer. Allows client code to read the token without relying on cookies.
          type: string
      required:
      - cookie_consent
      - id
      - token
      type: object
    PartnerEventIdResponse:
      nullable: true
      properties:
        name:
          description: Name of the partner event identifier (e.g. `order_id`).
          type: string
        value:
          description: Value of the partner event identifier.
          type: string
      type: object
    EventDispatcherRequest:
      properties:
        data:
          $ref: '#/components/schemas/EventSubmissionData'
        event_name:
          description: Name of the event being submitted (for example, `conversion` or `registration`). Required.
          type: string
        event_time:
          description: ISO 8601 timestamp of when the event occurred. Optional; defaults to the time the request is received. Use for backdated events.
          type: string
      required:
      - data
      - event_name
      - event_time
      type: object
    EventDispatcherAsyncResponse:
      properties:
        event_id:
          description: Unique identifier for the queued event. Person identification occurs asynchronously after the request returns.
          type: string
      required:
      - event_id
      type: object
    QualityResults:
      properties:
        quality_rule_results:
          items:
            $ref: '#/components/schemas/QualityRuleResult'
          type: array
        score:
          enum:
          - ERROR
          - HIGH
          - LOW
          type: string
      type: object
    StepSignal:
      properties:
        aliases:
          items:
            type: string
          type: array
          uniqueItems: true
        data:
          additionalProperties:
            type: object
          type: object
        first_site_visit:
          type: boolean
        name:
          type: string
        partner_event_id:
          $ref: '#/components/schemas/PartnerEventIdResponse'
        quality_results:
          $ref: '#/components/schemas/QualityResults'
      type: object
    EventSubmissionData:
      additionalProperties: true
      description: Open map of fields submitted with an event. May include keys beyond those listed here. `email` is the primary identity key and the only field that enables profile merging. `partner_user_id` is a secondary lookup key and is not guaranteed unique.
      example:
        email: user@example.com
        event_time: '2024-01-15T12:00:00Z'
        partner_user_id: usr_8392047156
        person_id: 7465313346145957284
      nullable: true
      properties:
        email:
          description: Primary identity key. The only data-map field that enables profile merging when submitted.
          example: user@example.com
          format: email
          type: string
        event_time:
          description: ISO 8601 timestamp of when the event occurred. Optional; defaults to the time the request is received. Use for backdated events. On wrapped request bodies this is an alternative to the top-level `event_time` field.
          example: '2024-01-15T12:00:00Z'
          format: date-time
          type: string
        partner_user_id:
          description: Secondary lookup key for an existing profile. Not guaranteed unique across your program.
          example: usr_8392047156
          type: string
        person_id:
          description: Extole person identifier. Numeric. Submit to target an existing profile instead of resolving by email or partner user id.
          example: 7465313346145957284
          format: int64
          type: integer
      type: object
    EventDispatcherResponse:
      properties:
        event_id:
          description: Unique identifier for the submitted event.
          type: string
        person_id:
          description: Extole person ID resolved from the event data.
          type: string
      required:
      - event_id
      - person_id
      type: object
    RestExceptionResponse:
      description: Represents the API error response
      properties:
        code:
          description: Specific error code for this error type, documented per endpoint
          type: string
        http_status_code:
          description: HTTP status code that was returned with this error, useful if client get response code
          format: int32
          type: integer
        message:
          description: User readable English description of the error
          type: string
        parameters:
          additionalProperties:
            description: Attributes related to the error, varies be error code, documented per endpoint
            type: object
          description: Attributes related to the error, varies be error code, documented per endpoint
          type: object
        unique_id:
          description: Unique id associated with this error, useful for discussions with Extole
          type: string
      required:
      - code
      - http_status_code
      - message
      - parameters
      - unique_id
      type: object
  securitySchemes:
    COOKIE:
      in: cookie
      name: extole_token
      type: apiKey
    HEADER:
      in: header
      name: Authorization
      type: apiKey
      x-bearer-format: bearer
    QUERY:
      in: query
      name: access_token
      type: apiKey
x-tagGroups:
- name: Integration API - Consumer to Extole
  tags:
  - Authentication
  - Content
  - Email
  - Events
  - Persons
  - Profile Assets
  - Profiles