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: examples: too_many_requests: $ref: '#/components/examples/too_many_requests' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Too Many Requests '503': content: application/json: examples: job_history_unavailable: $ref: '#/components/examples/job_history_unavailable' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Service Unavailable summary: List job execution history tags: - Batch Jobs x-extole-bundle: management x-extole-visibility: visible /v6/jobs/history/{historyId}: get: description: Returns a single file validation monitor execution history entry by execution chain id. operationId: getJobsHistoryEntry parameters: - description: Execution chain id for the history entry. in: path name: historyId required: true schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/JobHistoryResponse' description: The requested job execution history entry. '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: examples: too_many_requests: $ref: '#/components/examples/too_many_requests' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Too Many Requests '503': content: application/json: examples: job_history_unavailable: $ref: '#/components/examples/job_history_unavailable' schema: $ref: '#/components/schemas/RestExceptionResponse' description: Service Unavailable summary: Get a job execution history entry tags: - Batch Jobs x-extole-bundle: management x-extole-visibility: visible 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 batch_job_event_name_invalid: summary: batch_job_event_name_invalid value: code: batch_job_event_name_invalid http_status_code: 400 message: Invalid batch job event_name, name should have a value, max length 255 parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 job_history_unavailable: summary: job_history_unavailable value: code: job_history_unavailable http_status_code: 503 message: Job history is temporarily unavailable parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 batch_job_name_invalid: summary: batch_job_name_invalid value: code: batch_job_name_invalid http_status_code: 400 message: Invalid batch job name, name should have a value, max length 255 parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 batch_job_tag_invalid: summary: batch_job_tag_invalid value: code: batch_job_tag_invalid http_status_code: 400 message: Invalid batch job tag, name should have a value, max length 255 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 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 batch_job_data_source_empty: summary: batch_job_data_source_empty value: code: batch_job_data_source_empty http_status_code: 400 message: Data source is required parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 invalid_null: summary: invalid_null value: code: invalid_null http_status_code: 400 message: The attribute may be omitted but not nullified 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 job_history_not_found: summary: job_history_not_found value: code: job_history_not_found http_status_code: 400 message: Job history entry not found parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 batch_job_invalid_state_transition: summary: batch_job_invalid_state_transition value: code: batch_job_invalid_state_transition http_status_code: 400 message: Current state doesn't allow the specified operation 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 batch_job_locked: summary: batch_job_locked value: code: batch_job_locked http_status_code: 423 message: Batch job is locked by another process. Please try again later. 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 batch_job_delete_not_allowed: summary: batch_job_delete_not_allowed value: code: batch_job_delete_not_allowed http_status_code: 400 message: Batch job cannot be deleted while it's in current status parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 batch_job_unauthorized_scopes: summary: batch_job_unauthorized_scopes value: code: batch_job_unauthorized_scopes http_status_code: 400 message: Attempt to update scopes to unauthorized values parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 schemas: PatternNameMatchBatchJobColumnRequest: allOf: - $ref: '#/components/schemas/BatchJobColumnRequestBase' - properties: name_pattern: type: object type: enum: - PATTERN_NAME_MATCH type: string type: object required: - name_pattern - prefix - type - validation_policy type: object BatchJobDataSourceRequestBase: properties: type: enum: - AUDIENCE_LIST - FILE_ASSET - REPORT type: string type: object BatchJobCreateRequest: description: Body of a `POST /v6/batches` request. properties: columns: description: Column validation rules applied before the job begins dispatching. Each entry declares a column name and optional constraints; rows that fail validation are counted in `failed_rows`. items: $ref: '#/components/schemas/BatchJobColumnRequest' type: array uniqueItems: true data_source: $ref: '#/components/schemas/BatchJobDataSourceRequest' default_event_name: description: Fallback event name used when a row does not supply its own event name. Applied when `event_name` is omitted and no `event_name` column is present in the row. type: string event_columns: description: Column names in the data source whose values are used as event column values when dispatching each row. For example, `["person_id"]` will pass the row's `person_id` value as the identity key for event dispatch. items: description: Column names in the data source whose values are used as event column values when dispatching each row. For example, `["person_id"]` will pass the row's `person_id` value as the identity key for event dispatch. type: string type: array uniqueItems: true event_data: additionalProperties: description: Static key-value pairs merged into every dispatched event's data map. These are applied in addition to any per-row data derived from `event_columns`. type: string description: Static key-value pairs merged into every dispatched event's data map. These are applied in addition to any per-row data derived from `event_columns`. type: object event_name: description: Event name to dispatch for each row in the data source. When set, all rows dispatch this event regardless of any `event_name` column in the data. Omit to use the `default_event_name` or the per-row value from `event_columns`. type: string name: description: Human-readable label for the batch job. Used for display and filtering. Omit to leave unnamed. type: string scopes: description: 'Access-control scopes that restrict which user roles can interact with this job. Accepted values: `CLIENT_SUPERUSER`, `CLIENT_ADMIN`.' items: description: 'Access-control scopes that restrict which user roles can interact with this job. Accepted values: `CLIENT_SUPERUSER`, `CLIENT_ADMIN`.' enum: - CLIENT_ADMIN - CLIENT_SUPERUSER type: string type: array uniqueItems: true tags: description: Arbitrary string labels attached to the batch job for filtering and grouping. Tags are also surfaced in batch-job-created notifications. items: description: Arbitrary string labels attached to the batch job for filtering and grouping. Tags are also surfaced in batch-job-created notifications. type: string type: array uniqueItems: true required: - data_source type: object BatchJobColumnRequestBase: properties: prefix: type: string type: enum: - FULL_NAME_MATCH - PATTERN_NAME_MATCH type: string validation_policy: enum: - OPTIONAL - REQUIRED_COLUMN - REQUIRED_VALUE type: string type: object FullNameMatchBatchJobColumnRequest: allOf: - $ref: '#/components/schemas/BatchJobColumnRequestBase' - properties: name: type: string type: enum: - FULL_NAME_MATCH type: string type: object required: - name - prefix - type - validation_policy type: object TaskExecutionResponse: properties: context: additionalProperties: type: object type: object error_code: type: string error_message: type: string event_id: type: string event_time: $ref: '#/components/schemas/ZonedDateTime' sequence: format: int64 type: integer status: enum: - FAIL - SUCCESS type: string task_id: type: string type: object BatchJobUpdateRequest: description: Body of a `PUT /v6/batches/{batchId}` request. properties: name: description: Updated human-readable label for the batch job. Omit to leave unchanged. type: string scopes: description: 'Updated access-control scopes. Accepted values: `CLIENT_SUPERUSER`, `CLIENT_ADMIN`. Omit to leave unchanged.' items: description: 'Updated access-control scopes. Accepted values: `CLIENT_SUPERUSER`, `CLIENT_ADMIN`. Omit to leave unchanged.' enum: - CLIENT_ADMIN - CLIENT_SUPERUSER type: string type: array uniqueItems: true tags: description: Updated string labels for filtering and grouping. Replaces the existing tag set. Omit to leave unchanged. items: description: Updated string labels for filtering and grouping. Replaces the existing tag set. Omit to leave unchanged. type: string type: array uniqueItems: true type: object BatchJobDataSourceRequest: description: 'Data source for the batch job. Required. Specify one of: `REPORT` (a previously completed report), `AUDIENCE_LIST` (an audience list build), or `FILE_ASSET` (an uploaded file asset).' discriminator: mapping: AUDIENCE_LIST: '#/components/schemas/AudienceListBatchJobDataSourceRequest' FILE_ASSET: '#/components/schemas/FileAssetBatchJobDataSourceRequest' REPORT: '#/components/schemas/ReportBatchJobDataSourceRequest' propertyName: type oneOf: - $ref: '#/components/schemas/AudienceListBatchJobDataSourceRequest' - $ref: '#/components/schemas/FileAssetBatchJobDataSourceRequest' - $ref: '#/components/schemas/ReportBatchJobDataSourceRequest' AudienceListBatchJobDataSourceRequest: allOf: - $ref: '#/components/schemas/BatchJobDataSourceRequestBase' - properties: audience_list_id: type: string type: enum: - AUDIENCE_LIST type: string type: object required: - audience_list_id - type type: object FileAssetBatchJobDataSourceRequest: allOf: - $ref: '#/components/schemas/BatchJobDataSourceRequestBase' - properties: file_asset_id: type: string type: enum: - FILE_ASSET type: string type: object required: - file_asset_id - type type: object ReportBatchJobDataSourceRequest: allOf: - $ref: '#/components/schemas/BatchJobDataSourceRequestBase' - properties: report_id: type: string type: enum: - REPORT type: string type: object required: - report_id - type type: object BatchJobColumnRequest: description: Column validation rules applied before the job begins dispatching. Each entry declares a column name and optional constraints; rows that fail validation are counted in `failed_rows`. discriminator: mapping: FULL_NAME_MATCH: '#/components/schemas/FullNameMatchBatchJobColumnRequest' PATTERN_NAME_MATCH: '#/components/schemas/PatternNameMatchBatchJobColumnRequest' propertyName: type oneOf: - $ref: '#/components/schemas/FullNameMatchBatchJobColumnRequest' - $ref: '#/components/schemas/PatternNameMatchBatchJobColumnRequest' ZonedDateTime: description: '[RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) or [RFC 9557](https://datatracker.ietf.org/doc/html/rfc9557#section-4) date-time with a numeric [UTC offset](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and an optional [IANA time-zone](https://datatracker.ietf.org/doc/html/rfc9557#section-4) suffix in square brackets. Precision up to milliseconds.' example: '2025-10-24T02:00:00-07:00' pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,3})?(Z|[+-](?:[01][0-9]|2[0-3]):[0-5][0-9])(\[[^\]]+\])?$ type: string 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 JobHistoryResponse: properties: client_id: type: string ended_at: $ref: '#/components/schemas/ZonedDateTime' history_id: type: string job_id: type: string started_at: $ref: '#/components/schemas/ZonedDateTime' status: enum: - FAIL - IN_PROGRESS - SUCCESS type: string task_executions: items: $ref: '#/components/schemas/TaskExecutionResponse' type: array required: - client_id - ended_at - history_id - job_id - started_at - status - task_executions 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