---
title: "Create a batch job"
method: POST
path: "/v6/batches"
tags: ["Batch Jobs"]
---

# Create a batch job

`POST /v6/batches`

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.

## Request body

- BatchJobCreateRequest — Body of a `POST /v6/batches` request.
  - `columns` BatchJobColumnRequest[] — 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`.
    - union — 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`.
      - FullNameMatchBatchJobColumnRequest
        - `prefix` string, required
        - `type` 'FULL_NAME_MATCH', required
        - `validation_policy` 'OPTIONAL' | 'REQUIRED_COLUMN' | 'REQUIRED_VALUE', required
        - `name` string, required
      - PatternNameMatchBatchJobColumnRequest
        - `prefix` string, required
        - `type` 'PATTERN_NAME_MATCH', required
        - `validation_policy` 'OPTIONAL' | 'REQUIRED_COLUMN' | 'REQUIRED_VALUE', required
        - `name_pattern` object, required
  - `data_source` union, required — 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).
    - AudienceListBatchJobDataSourceRequest
      - `type` 'AUDIENCE_LIST', required
      - `audience_list_id` string, required
    - FileAssetBatchJobDataSourceRequest
      - `type` 'FILE_ASSET', required
      - `file_asset_id` string, required
    - ReportBatchJobDataSourceRequest
      - `type` 'REPORT', required
      - `report_id` string, required
  - `default_event_name` string — 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.
  - `event_columns` string[] — 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.
  - `event_data` object — 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`.
  - `event_name` string — 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`.
  - `name` string — Human-readable label for the batch job. Used for display and filtering. Omit to leave unnamed.
  - `scopes` string[] — Access-control scopes that restrict which user roles can interact with this job. Accepted values: `CLIENT_SUPERUSER`, `CLIENT_ADMIN`.
  - `tags` string[] — Arbitrary string labels attached to the batch job for filtering and grouping. Tags are also surfaced in batch-job-created notifications.

## Response `200`

Batch job created. Returns the full job record with an initial `status` of `PENDING`.

## Other responses

- `400` — 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` — Missing or invalid access token.
- `402` — Payment Required
- `403` — Forbidden
- `415` — Unsupported Media Type
- `429` — Too Many Requests

---

[API](https://skmtc.net/extole/apis/integration-api-server-to-extole.md) · [All operations](https://skmtc.net/extole/apis/integration-api-server-to-extole/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/extole/integration-api-server-to-extole/revisions/c16e62e66755/schema)