---
title: "Create a Batch Job"
method: POST
path: "/batch-jobs"
tags: ["importers"]
---

# Create a Batch Job

`POST /batch-jobs`

## Request

- Base URL: `https://api.withpersona.com/api/v1`
- URL: `https://api.withpersona.com/api/v1/batch-jobs`
- Auth: HTTP bearer

Submits a batch of rows to update or upsert Accounts, or update Inquiries, in bulk. Persona
processes the rows asynchronously as a Batch Job; poll the returned job or retrieve its
errors to check progress.

- **`object: account`** supports `operation: update` (lookup by `token` or `reference_id`) or
  `operation: upsert` (lookup by `reference_id` only, and requires `account_type_id` on the
  pipeline or on each row).
- **`object: inquiry`** only supports `operation: update` with `lookup_field: token`.

## Query parameters

- `include` string
- `fields` object

## Headers

- `Key-Inflection` 'camel' | 'kebab' | 'snake'
- `Idempotency-Key` string
- `Persona-Version` '2026-09-29' | '2025-12-08' | '2025-10-27' | '2023-01-05' | '2022-09-01' | '2021-08-18' | '2021-07-05' | '2021-02-21' | '2020-05-18': Server API version. More info on versioning can be found [here](https://docs.withpersona.com/versioning).

## Request body

- object
  - `data` BatchJobsPostRequestBodyContentApplicationJsonSchemaData, required
    - `attributes` BatchJobsPostRequestBodyContentApplicationJsonSchemaDataAttributes, required
      - `operation` string, required: Whether to only update existing objects, or create them if they don't already exist. One of `update` or `upsert`. `upsert` is only supported for `object: account`.
      - `object` string, required: The kind of object each row updates. One of `account` or `inquiry`.
      - `lookup-field` string, required: The field used to find the object each row applies to. One of `token` or `reference_id`. `token` is required for `object: inquiry`.
      - `emit-events` boolean: Whether to emit events for objects affected by this run. Defaults to `true`. When `false` and `object` is `account`: suppresses the `account.updated-fields` event, and suppresses `account.tag-added` / `account.tag-removed` (so workflows and webhooks that trigger on those events do not run for this row). When `false` and `object` is `inquiry`: has no effect today, since updating an Inquiry's tags or fields through this endpoint does not emit any event regardless of this flag. In both cases, this only suppresses events -- it never affects the write itself, and Elasticsearch reindexing and the graph Kafka sync are not events and always run.
      - `account-type-id` string: The default Account Type token to use for rows that create a new Account and don't specify their own `account_type_id`. Only applicable when `object` is `account`.
      - `rows` object[], required: The rows to process, up to 1000 rows per request. Each row is a flat object whose keys are field names (for example `reference_id`, `token`, `account_type_id`, or a custom field key) and whose values are the data to write.

## Response `202`

The Batch Job has been created and processing has started.

- ImportersCreateABatchJobResponse202
  - `data` BatchJob, required: A Batch Job object.
    - `type` 'batch-job'
    - `id` string
    - `attributes` BatchJobAttributes
      - `status` string: Current status of the batch job. Possible values include `pending`, `running`, `paused`, `canceled`, `completed`, `errored`, and `killed`.
      - `run-count` integer: Number of times this batch job has been executed
      - `started-at` string, date-time, nullable: When the batch job started processing
      - `ended-at` string, date-time, nullable: When the batch job finished processing
      - `created-at` string, date-time: When the batch job was created
      - `updated-at` string, date-time: When the batch job was last updated
      - `redacted-at` string, date-time, nullable: When the batch job was redacted
      - `run-data` BatchJobAttributesRunData: Runtime data and statistics for the batch job
        - `column-names` string[]: Names of columns being processed
        - `error-count` integer: Number of errors encountered
        - `rows-read` integer: Number of rows read from the source
        - `row-count` integer: Total number of rows processed
        - `success-count` integer: Number of rows successfully processed
        - `created-count` integer: Number of new records created
        - `updated-count` integer: Number of existing records updated

## Other responses

- `400`: The request was unacceptable, often due to invalid parameters.
- `401`: An invalid API key was provided.
- `403`: The given API key doesn’t have permissions to perform the request or a quota has been exceeded.
- `409`: The request conflicts with another request, often due to attempting to create a duplicate resource.
- `422`: The request modifies the resource in an unacceptable way, often due to an invalid action or parameter.
- `429`: Your organization’s rate limit has been exceeded. We recommend an exponential backoff on requests.

---

[API](https://skmtc.dev/withpersona/apis/withpersona-7.md) - [All operations](https://skmtc.dev/withpersona/apis/withpersona-7/llms.txt) - [OpenAPI document](https://skmtc.dev/withpersona/apis/withpersona-7/revisions/904c4b28844f?raw)