---
title: "Create an upload batch"
method: POST
path: "/api/v1/upload-batches"
tags: ["Batches"]
---

# Create an upload batch

`POST /api/v1/upload-batches`

## Request

- Base URL: `https://app.probbai.com`
- URL: `https://app.probbai.com/api/v1/upload-batches`
- Auth: HTTP bearer

Queue several uploads in one durable request and track outcomes by your own itemKey. Use this to process an application import without coordinating every admission yourself.

## Before you call

Supply 1–20 items, at most 256 KiB JSON, unique itemKey values, and an Idempotency-Key. Only one batch of each kind can be active per workspace.

**Required scope:** `analyses:write`.

## What happens next

A 202 returns batchId and statusUrl. Items can succeed or fail independently. Each successful item creates a preparation, not an analysis. PUT each file to its item upload URL before quoting analyses.

## Recovery

Keep successful resource IDs. Capacity-limited items can wait up to the admission deadline; inspect per-item errorCode. Retry failed items deliberately in a new batch; analysis/interview items need fresh quotes. Foreign or unknown resource IDs reject the envelope.

[Follow the complete workflow](/integration-bulk/) · [Errors and retries](/api-errors/)

## Headers

- `Idempotency-Key` string, required

## Request body

- UploadBatchInput
  - `jobDescription` union: Role context: inline text or a saved job ID on input; selected role fields on a report response.
    - object
      - `kind` 'text', required: Variant selector. For job input use text or existing; for batches identifies uploads, analyses, or interviews.
      - `text` string, required: Inline job-description text, up to 50,000 characters; describe responsibilities and required evidence.
    - object
      - `kind` 'existing', required: Variant selector. For job input use text or existing; for batches identifies uploads, analyses, or interviews.
      - `id` string, required: Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI.
      - `expectedRevision` string: Optional SHA-256 job revision from discovery. Reject preparation if the saved role changed since you reviewed it.
  - `items` object[], required: Page or batch entries. An empty list is valid; use the cursor or individual item states to decide what happens next.
    - `itemKey` string, required: Your unique identifier within this batch, used to match each outcome to its input. It is not the HTTP idempotency key.
    - `input` object, required: The request for this individual batch item, using the corresponding single-operation fields.
      - `externalReference` object: Your application identity: source plus id, unique within the workspace. Prefer an application ID rather than personal information.
        - `source` string, required: Lowercase external-system slug, such as my-ats. Combined with id to identify one application in the workspace.
        - `id` string, required: Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI.
      - `fileName` string, required: Original PDF or DOCX filename, including extension. Paths and control characters are rejected.
      - `fileSize` integer, required: Exact file byte length, from 1 to 10,485,760. This is not the number of characters or a megabyte count.
      - `mimeType` 'application/pdf' | 'application/vnd.openxmlformats-officedocument.wordprocessingml.document', required: File content type. The file extension, declared type, and uploaded content must agree.
      - `jobDescription` union: Role context: inline text or a saved job ID on input; selected role fields on a report response.
        - object
          - `kind` 'text', required: Variant selector. For job input use text or existing; for batches identifies uploads, analyses, or interviews.
          - `text` string, required: Inline job-description text, up to 50,000 characters; describe responsibilities and required evidence.
        - object
          - `kind` 'existing', required: Variant selector. For job input use text or existing; for batches identifies uploads, analyses, or interviews.
          - `id` string, required: Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI.
          - `expectedRevision` string: Optional SHA-256 job revision from discovery. Reject preparation if the saved role changed since you reviewed it.

## Response `202`

A 202 returns batchId and statusUrl. Items can succeed or fail independently. Each successful item creates a preparation, not an analysis. PUT each file to its item upload URL before quoting analyses.

- object
  - `data` BatchAdmission, required
    - `batchId` string, required: Identifier returned when the batch was accepted; use it to retrieve item outcomes.
    - `statusUrl` string, required: Relative API path to poll with the same workspace API key. Resolve against your application origin.

## Other responses

- `400`: Invalid input or cursor
- `401`: Invalid, expired, or revoked API key
- `403`: Disabled organisation or missing scope
- `404`: The resource is absent, expired, deleted, or unavailable in this workspace. Verify the resource ID and key's workspace.
- `405`: Method not allowed; consult Allow for supported methods
- `409`: Keep successful resource IDs. Capacity-limited items can wait up to the admission deadline; inspect per-item errorCode. Retry failed items deliberately in a new batch; analysis/interview items need fresh quotes. Foreign or unknown resource IDs reject the envelope.
- `429`: Request limit exceeded
- `500`: Unexpected failure
- `503`: Service unavailable

---

[API](https://skmtc.dev/probbai/apis/probb-ai-customer-api.md) · [All operations](https://skmtc.dev/probbai/apis/probb-ai-customer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/probbai/apis/probb-ai-customer-api/revisions/33a3294530e4?raw)