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 Content 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: Content
paths:
  /api/v6/zones:
    post:
      description: API-friendly zone rendering at `POST /api/v6/zones`. Intended for backend rendering where the caller supplies a bearer access token directly. Renders the zone identified by `event_name` in the JSON request body and returns the structured zone content as JSON. Returns an error when no content backs the zone. For browser or in-app rendering use `POST /zones` instead.
      operationId: renderZone
      requestBody:
        content:
          application/json:
            example:
              data:
                data_key: {}
              event_name: event_name
              id_token: id_token
              jwt: jwt
            schema:
              $ref: '#/components/schemas/RenderZoneRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/RenderZoneRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZoneResponse'
          description: Zone content.
        '400':
          content:
            application/json:
              examples:
                invalid_creative_result:
                  $ref: '#/components/examples/invalid_creative_result'
                invalid_zone_name:
                  $ref: '#/components/examples/invalid_zone_name'
                missing_zone_name:
                  $ref: '#/components/examples/missing_zone_name'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: 'Zone rendering failed: `missing_zone_name` if no zone name was supplied in the request body, `invalid_zone_name` if the name is not recognised by the client''s campaign configuration, or `invalid_creative_result` if the configured creative did not return valid JSON.'
        '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
      summary: Render a zone
      tags:
      - Content
      x-extole-bundle: integration-consumer-to-extole
      x-extole-visibility: visible
  /api/v6/zones/{event_name}:
    post:
      description: API-friendly zone rendering at `POST /api/v6/zones/{event_name}`. Intended for backend rendering where the caller supplies a bearer access token directly. Renders the zone identified by the `event_name` path parameter and returns the structured zone content as JSON. Pass zone input data in the request body. Returns an error when no content backs the zone. For browser or in-app rendering use `POST /zones/{zone_name}` instead.
      operationId: renderZoneByEventName
      parameters:
      - in: path
        name: event_name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              value: {}
            schema:
              additionalProperties:
                type: object
              type: object
          application/x-www-form-urlencoded:
            schema:
              additionalProperties:
                type: object
              type: object
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZoneResponse'
          description: Zone content.
        '400':
          content:
            application/json:
              examples:
                invalid_creative_result:
                  $ref: '#/components/examples/invalid_creative_result'
                invalid_zone_name:
                  $ref: '#/components/examples/invalid_zone_name'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: 'Zone rendering failed: `invalid_zone_name` if the zone name from the URL path is not recognised by the client''s campaign configuration, or `invalid_creative_result` if the configured creative did not return valid JSON.'
        '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
      summary: Render a named zone
      tags:
      - Content
      x-extole-bundle: integration-consumer-to-extole
      x-extole-visibility: visible
  /zones:
    post:
      description: 'Web-friendly zone rendering at `POST /zones`. Intended for direct use from a browser page or web SDK embed — accepts form-encoded, plain-text, and multipart bodies in addition to JSON, and handles cookie-based identity automatically. Renders the zone identified by `event_name` in the request body, applies any other body fields as targeting data passed to the creative, and returns the rendered creative content (HTML, JavaScript, JSON, or plain text). If `event_name` is omitted, returns an empty 200 with `Extole-Log: target zone=unknown`; the access token is still allocated and written as a cookie. For backend zone rendering use `POST /api/v6/zones` instead.'
      operationId: renderZoneWeb
      requestBody:
        content:
          application/json:
            example:
              data:
                data_key: {}
              event_name: event_name
              id_token: id_token
              jwt: jwt
            schema:
              $ref: '#/components/schemas/RenderZoneRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/RenderZoneRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/RenderZoneRequest'
          text/plain:
            schema:
              $ref: '#/components/schemas/RenderZoneRequest'
      responses:
        '200':
          content:
            '*/*':
              schema:
                type: string
          description: 'Rendered zone content. The response body shape varies by the zone''s creative configuration: HTML, JavaScript, JSON, or plain text.'
        '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
      summary: Render a zone with the name in the body
      tags:
      - Content
      x-extole-bundle: integration-consumer-to-extole
      x-extole-visibility: visible
  /zones/{zone_name}:
    post:
      description: Web-friendly zone rendering at `POST /zones/{zone_name}`. Intended for direct use from a browser page or web SDK embed — accepts form-encoded and multipart bodies in addition to JSON, and handles cookie-based identity automatically. Renders the zone identified by `zone_name` and returns its content (HTML, JavaScript, JSON, or plain text). For backend zone rendering use `POST /api/v6/zones/{event_name}` instead.
      operationId: renderZoneByNameWeb
      parameters:
      - in: path
        name: zone_name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              value: {}
            schema:
              additionalProperties:
                type: object
              type: object
          application/x-www-form-urlencoded:
            schema:
              additionalProperties:
                type: object
              type: object
          multipart/form-data:
            schema:
              additionalProperties:
                type: object
              type: object
          text/plain:
            schema:
              additionalProperties:
                type: object
              type: object
      responses:
        '200':
          content:
            '*/*':
              schema:
                type: string
          description: 'Rendered zone content. The response body shape varies by the zone''s creative configuration: HTML, JavaScript, JSON, or plain text.'
        '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
      summary: Render a named zone for web-page embedding
      tags:
      - Content
      x-extole-bundle: integration-consumer-to-extole
      x-extole-visibility: visible
  /web/me/assets/download:
    get:
      operationId: downloadAssetByName_2
      parameters:
      - in: query
        name: name
        schema:
          type: string
      - in: query
        name: default_url
        schema:
          type: string
      responses:
        '200':
          content:
            '*/*': {}
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                asset_content_not_downloadable:
                  $ref: '#/components/examples/asset_content_not_downloadable'
                asset_not_found:
                  $ref: '#/components/examples/asset_not_found'
                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:
      - Content
      x-extole-bundle: integration-consumer-to-extole
      x-extole-visibility: expert
  /web/me/assets/{assetId}/download:
    get:
      operationId: downloadAssetById_2
      parameters:
      - in: path
        name: assetId
        required: true
        schema:
          type: string
      - in: query
        name: default_url
        schema:
          type: string
      responses:
        '200':
          content:
            '*/*': {}
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                asset_content_not_downloadable:
                  $ref: '#/components/examples/asset_content_not_downloadable'
                asset_not_found:
                  $ref: '#/components/examples/asset_not_found'
                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:
      - Content
      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_zone_name:
      summary: invalid_zone_name
      value:
        code: invalid_zone_name
        http_status_code: 403
        message: Invalid zone name (not an EMAIL zone)
        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
    asset_not_found:
      summary: asset_not_found
      value:
        code: asset_not_found
        http_status_code: 400
        message: Asset not found
        parameters: {}
        unique_id: 00000000-0000-0000-0000-000000000000
    invalid_creative_result:
      summary: invalid_creative_result
      value:
        code: invalid_creative_result
        http_status_code: 400
        message: Configured creative did not return json.
        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
    missing_zone_name:
      summary: missing_zone_name
      value:
        code: missing_zone_name
        http_status_code: 400
        message: Zone name must be present
        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
    asset_content_not_downloadable:
      summary: asset_content_not_downloadable
      value:
        code: asset_content_not_downloadable
        http_status_code: 400
        message: Asset content could not be downloaded
        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
  schemas:
    ZoneResponse:
      properties:
        campaign_id:
          description: Extole campaign id that served this zone. Absent if not determinable.
          type: string
        data:
          additionalProperties:
            description: Creative output for this zone. Structure varies by campaign configuration.
            type: object
          description: Creative output for this zone. Structure varies by campaign configuration.
          type: object
        event_id:
          description: Extole event id generated for this zone render request.
          type: string
      required:
      - campaign_id
      - data
      - event_id
      type: object
    RenderZoneRequest:
      properties:
        data:
          additionalProperties:
            type: object
          nullable: true
          type: object
        event_name:
          type: string
        id_token:
          nullable: true
          type: string
        jwt:
          nullable: true
          type: string
      required:
      - data
      - event_name
      - id_token
      - jwt
      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