> ## Documentation Index > Fetch the complete documentation index at: https://doc.extole.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a batch job > 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. ## OpenAPI ````yaml /api-reference/integration-server-to-extole.json post /v6/batches openapi: 3.0.1 info: description: >- Server-to-Extole integration endpoints: event submission, person lookup, zone rendering, token management, and reward retrieval for backend services authenticating with client credentials. title: Integration API - Server to Extole version: '1.0' servers: - description: Production url: https://api.extole.io security: - HEADER: [] - QUERY: [] - COOKIE: [] tags: - name: Authentication - name: Batch Jobs - name: Events - name: Files - name: Persons - name: Reward Suppliers - name: Rewards - name: SFTP Servers - name: Zone Rendering paths: /v6/batches: post: tags: - Batch Jobs summary: Create a batch job 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 components: schemas: 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 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 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: $ref: '#/components/schemas/FullNameMatchBatchJobColumnRequest' PATTERN_NAME_MATCH: $ref: '#/components/schemas/PatternNameMatchBatchJobColumnRequest' propertyName: type oneOf: - title: FULL_NAME_MATCH allOf: - $ref: '#/components/schemas/FullNameMatchBatchJobColumnRequest' - title: PATTERN_NAME_MATCH allOf: - $ref: '#/components/schemas/PatternNameMatchBatchJobColumnRequest' 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: $ref: '#/components/schemas/AudienceListBatchJobDataSourceRequest' FILE_ASSET: $ref: '#/components/schemas/FileAssetBatchJobDataSourceRequest' REPORT: $ref: '#/components/schemas/ReportBatchJobDataSourceRequest' propertyName: type oneOf: - title: AUDIENCE_LIST allOf: - $ref: '#/components/schemas/AudienceListBatchJobDataSourceRequest' - title: FILE_ASSET allOf: - $ref: '#/components/schemas/FileAssetBatchJobDataSourceRequest' - title: REPORT allOf: - $ref: '#/components/schemas/ReportBatchJobDataSourceRequest' 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 title: FULL_NAME_MATCH 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 title: PATTERN_NAME_MATCH 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 title: AUDIENCE_LIST 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 title: FILE_ASSET ReportBatchJobDataSourceRequest: allOf: - $ref: '#/components/schemas/BatchJobDataSourceRequestBase' - properties: report_id: type: string type: enum: - REPORT type: string type: object required: - report_id - type type: object title: REPORT 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 BatchJobDataSourceRequestBase: properties: type: enum: - AUDIENCE_LIST - FILE_ASSET - REPORT type: string type: object examples: 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 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 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 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 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 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 invalid_parameter: summary: invalid_parameter value: code: invalid_parameter http_status_code: 400 message: Parameter is invalid. parameters: {} unique_id: 00000000-0000-0000-0000-000000000000 missing_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 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 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 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 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 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 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 securitySchemes: HEADER: in: header name: Authorization type: apiKey x-bearer-format: bearer QUERY: in: query name: access_token type: apiKey COOKIE: in: cookie name: extole_token type: apiKey ````