Extole Batch Jobs 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 Batch Jobs 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: Batch Jobs
paths:
  /v6/batches:
    get:
      description: Returns a paginated list of batch jobs for the authenticated client. Filter by `name`, `event_name`, `tags`, `status`, or `user_id`. Results are ordered by creation date descending. Default page size is 100.
      operationId: listBatches
      parameters:
      - in: query
        name: name
        schema:
          type: string
      - in: query
        name: event_name
        schema:
          type: string
      - in: query
        name: user_id
        schema:
          type: string
      - in: query
        name: tags
        schema:
          items:
            type: string
          type: array
          uniqueItems: true
      - in: query
        name: status
        schema:
          items:
            enum:
            - CANCELED
            - DISPATCHING
            - DONE
            - EXPIRED
            - FAILED
            - IN_PROGRESS
            - PENDING
            - QUEUED
            type: string
          type: array
          uniqueItems: true
      - in: query
        name: limit
        schema:
          format: int32
          type: integer
      - in: query
        name: offset
        schema:
          format: int32
          type: integer
      responses:
        '200':
          description: List of batch jobs matching the filter criteria.
        '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: Missing or invalid access token.
        '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 batch jobs
      tags:
      - Batch Jobs
      x-extole-bundle: integration-server-to-extole
      x-extole-visibility: visible
    post:
      description: Creates a new asynchronous batch job that reads its data source row-by-row and dispatches a consumer event for each row. The data source can be a previously run report, an audience list, or an uploaded file asset (CSV, PSV, or JSON). The job begins processing immediately after creation; poll `GET /v6/batches/{batchId}` to monitor `status`. For small inline batches of events, use `POST /v6/async-events` in the event-api instead.
      operationId: createBatch
      requestBody:
        content:
          application/json:
            example:
              columns:
              - name: name
                prefix: prefix
                type: FULL_NAME_MATCH
                validation_policy: OPTIONAL
              data_source:
                audience_list_id: audience_list_id
                type: AUDIENCE_LIST
              default_event_name: default_event_name
              event_columns:
              - event_column
              event_data:
                event_data_key: event_data_key
              event_name: event_name
              name: name
              scopes:
              - CLIENT_ADMIN
              tags:
              - tag
            schema:
              $ref: '#/components/schemas/BatchJobCreateRequest'
        description: Batch job creation request.
        required: true
      responses:
        '200':
          description: Batch job created. Returns the full job record with an initial `status` of `PENDING`.
        '400':
          content:
            application/json:
              examples:
                batch_job_data_source_empty:
                  $ref: '#/components/examples/batch_job_data_source_empty'
                batch_job_event_name_invalid:
                  $ref: '#/components/examples/batch_job_event_name_invalid'
                batch_job_name_invalid:
                  $ref: '#/components/examples/batch_job_name_invalid'
                batch_job_tag_invalid:
                  $ref: '#/components/examples/batch_job_tag_invalid'
                batch_job_unauthorized_scopes:
                  $ref: '#/components/examples/batch_job_unauthorized_scopes'
                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: 'Validation error. Check the `code` field — common causes: missing or invalid `data_source`, unsupported `event_name` format, or a column reference that doesn''t exist in the data source.'
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Missing or invalid access token.
        '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 a batch job
      tags:
      - Batch Jobs
      x-extole-bundle: integration-server-to-extole
      x-extole-visibility: visible
  /v6/batches/{batchId}:
    get:
      description: 'Returns the full record for a single batch job, including current `status`, `success_rows`, `failed_rows`, and data source configuration. Poll this endpoint to monitor job progress until `status` reaches a terminal state: `DONE`, `FAILED`, `CANCELED`, or `EXPIRED`.'
      operationId: getBatch
      parameters:
      - description: Batch job ID.
        in: path
        name: batchId
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Batch job record.
        '400':
          content:
            application/json:
              examples:
                batch_job_delete_not_allowed:
                  $ref: '#/components/examples/batch_job_delete_not_allowed'
                batch_job_invalid_state_transition:
                  $ref: '#/components/examples/batch_job_invalid_state_transition'
                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: Missing or invalid access token.
        '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
        '404':
          description: Batch job not found or does not belong to this client.
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '423':
          content:
            application/json:
              examples:
                batch_job_locked:
                  $ref: '#/components/examples/batch_job_locked'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Error
        '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 a batch job
      tags:
      - Batch Jobs
      x-extole-bundle: integration-server-to-extole
      x-extole-visibility: visible
    put:
      description: 'Updates the mutable fields of an existing batch job: `name`, `tags`, and `scopes`. The job must not be in a terminal state (`DONE`, `FAILED`, `CANCELED`, or `EXPIRED`). Data source, event name, and column mappings are immutable after creation.'
      operationId: updateBatch
      parameters:
      - description: Batch job ID.
        in: path
        name: batchId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              name: name
              scopes:
              - CLIENT_ADMIN
              tags:
              - tag
            schema:
              $ref: '#/components/schemas/BatchJobUpdateRequest'
      responses:
        '200':
          description: Batch job updated. Returns the full updated job record.
        '400':
          content:
            application/json:
              examples:
                batch_job_data_source_empty:
                  $ref: '#/components/examples/batch_job_data_source_empty'
                batch_job_delete_not_allowed:
                  $ref: '#/components/examples/batch_job_delete_not_allowed'
                batch_job_event_name_invalid:
                  $ref: '#/components/examples/batch_job_event_name_invalid'
                batch_job_invalid_state_transition:
                  $ref: '#/components/examples/batch_job_invalid_state_transition'
                batch_job_name_invalid:
                  $ref: '#/components/examples/batch_job_name_invalid'
                batch_job_tag_invalid:
                  $ref: '#/components/examples/batch_job_tag_invalid'
                batch_job_unauthorized_scopes:
                  $ref: '#/components/examples/batch_job_unauthorized_scopes'
                binding_error:
                  $ref: '#/components/examples/binding_error'
                invalid_json:
                  $ref: '#/components/examples/invalid_json'
                invalid_null:
                  $ref: '#/components/examples/invalid_null'
                invalid_parameter:
                  $ref: '#/components/examples/invalid_parameter'
                missing_request_body:
                  $ref: '#/components/examples/missing_request_body'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Invalid field value or omissible constraint violation.
        '401':
          content:
            application/json:
              examples:
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Missing or invalid access token.
        '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
        '404':
          description: Batch job not found or does not belong to this client.
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '423':
          content:
            application/json:
              examples:
                batch_job_locked:
                  $ref: '#/components/examples/batch_job_locked'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Error
        '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 a batch job
      tags:
      - Batch Jobs
      x-extole-bundle: integration-server-to-extole
      x-extole-visibility: visible
    delete:
      description: Permanently deletes a batch job record. The job must be in a terminal state (`DONE`, `FAILED`, `CANCELED`, or `EXPIRED`). This action is irreversible; the job record cannot be recovered after deletion.
      operationId: deleteBatch
      parameters:
      - description: Batch job ID.
        in: path
        name: batchId
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Batch job deleted. Returns the final job record at the time of deletion.
        '400':
          content:
            application/json:
              examples:
                batch_job_delete_not_allowed:
                  $ref: '#/components/examples/batch_job_delete_not_allowed'
                batch_job_invalid_state_transition:
                  $ref: '#/components/examples/batch_job_invalid_state_transition'
                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: Missing or invalid access token.
        '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
        '404':
          description: Batch job not found or does not belong to this client.
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '423':
          content:
            application/json:
              examples:
                batch_job_locked:
                  $ref: '#/components/examples/batch_job_locked'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Error
        '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 a batch job
      tags:
      - Batch Jobs
      x-extole-bundle: integration-server-to-extole
      x-extole-visibility: visible
  /v6/batches/{batchId}/cancel:
    post:
      description: Requests cancellation of a batch job. The job transitions to `CANCELED` status. Only jobs in a non-terminal state (`PENDING`, `QUEUED`, `IN_PROGRESS`, or `DISPATCHING`) can be canceled.
      operationId: cancelBatch
      parameters:
      - description: Batch job ID.
        in: path
        name: batchId
        required: true
        schema:
          type: string
      responses:
        '200':
          description: 'Cancellation accepted. Returns the updated job record with `status: CANCELED`.'
        '400':
          content:
            application/json:
              examples:
                batch_job_delete_not_allowed:
                  $ref: '#/components/examples/batch_job_delete_not_allowed'
                batch_job_invalid_state_transition:
                  $ref: '#/components/examples/batch_job_invalid_state_transition'
                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: Missing or invalid access token.
        '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
        '404':
          description: Batch job not found or does not belong to this client.
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '423':
          content:
            application/json:
              examples:
                batch_job_locked:
                  $ref: '#/components/examples/batch_job_locked'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Error
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: Cancel a batch job
      tags:
      - Batch Jobs
      x-extole-bundle: integration-server-to-extole
      x-extole-visibility: visible
  /v6/batches/{batchId}/expire:
    post:
      description: Marks a completed batch job as expired, releasing associated resources. Only jobs in terminal state (`DONE`, `FAILED`, or `CANCELED`) can be expired. Once expired, the job record remains queryable but its data source reference is released.
      operationId: expireBatch
      parameters:
      - description: Batch job ID.
        in: path
        name: batchId
        required: true
        schema:
          type: string
      responses:
        '200':
          description: 'Batch job expired. Returns the updated job record with `status: EXPIRED`.'
        '400':
          content:
            application/json:
              examples:
                batch_job_delete_not_allowed:
                  $ref: '#/components/examples/batch_job_delete_not_allowed'
                batch_job_invalid_state_transition:
                  $ref: '#/components/examples/batch_job_invalid_state_transition'
                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: Missing or invalid access token.
        '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
        '404':
          description: Batch job not found or does not belong to this client.
        '415':
          content:
            application/json:
              examples:
                unsupported_media_type:
                  $ref: '#/components/examples/unsupported_media_type'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Unsupported Media Type
        '423':
          content:
            application/json:
              examples:
                batch_job_locked:
                  $ref: '#/components/examples/batch_job_locked'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Error
        '429':
          content:
            application/json:
              examples:
                too_many_requests:
                  $ref: '#/components/examples/too_many_requests'
              schema:
                $ref: '#/components/schemas/RestExceptionResponse'
          description: Too Many Requests
      summary: Expire a batch job
      tags:
      - Batch Jobs
      x-extole-bundle: integration-server-to-extole
      x-extole-visibility: visible
  /v6/jobs/history:
    get:
      description: Returns file validation monitor execution history aggregated across all pods.
      operationId: listJobsHistory
      parameters:
      - in: query
        name: limit
        schema:
          format: int32
          type: integer
      - in: query
        name: offset
        schema:
          format: int32
          type: integer
      - in: query
        name: job_id
        schema:
          type: string
      - in: query
        name: status
        schema:
          enum:
          - FAIL
          - IN_PROGRESS
          - SUCCESS
          type: string
      - in: query
        name: start_date
        schema:
          $ref: '#/components/schemas/ZonedDateTime'
      - in: query
        name: end_date
        schema:
          $ref: '#/components/schemas/ZonedDateTime'
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/JobHistoryResponse'
                type: array
          description: Job execution history entries.
        '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'
                job_history_not_found:
                  $ref: '#/components/examples/job_history_not_found'
                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:
       

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