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

# Create a batch

`POST /v1/batches`

## Request

- Base URL: `https://api.castpdf.com`
- URL: `https://api.castpdf.com/v1/batches`
- Auth: HTTP bearer

One PDF per item (or spreadsheet row) from one template, rendered in the background. batch.completed is sent when every item is done; the ZIP link is on the batch.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `template_id` string, required
  - `template_version` integer
  - `items` object[]
    - `data` object
    - `filename` string
    - `metadata` object
    - `deliver` object
      - `email` object
        - `to` string
        - `subject` string
        - `message` string
        - `reply_to` string
  - `spreadsheet` object
    - `filename` string, required
    - `content_base64` string, required
    - `mapping` object
    - `email_column` string
  - `filename_pattern` string
  - `mode` 'fast' | 'print'
  - `format` union
    - 'A4' | 'A5' | 'Letter' | 'Legal'
    - object
      - `width` string, required
      - `height` string, required
  - `orientation` 'portrait' | 'landscape'
  - `margins` string
  - `deliver` object
    - `email` object
      - `to` string
      - `subject` string
      - `message` string
      - `reply_to` string
  - `metadata` object
  - `test` boolean

## Response `202`

Queued.

- Batch
  - `id` string, uuid
  - `status` 'queued' | 'processing' | 'completed' | 'canceled'
  - `livemode` boolean
  - `source` 'api' | 'spreadsheet'
  - `template_id` string, uuid
  - `template_version` integer
  - `total` integer
  - `queued` integer
  - `processing` integer
  - `succeeded` integer
  - `failed` integer
  - `canceled` integer
  - `created_at` string, date-time
  - `completed_at` string, date-time, nullable
  - `zip` object, nullable
    - `url` string, uri
    - `expires_at` string, date-time
    - `bytes` integer
  - `metadata` object, nullable

## Other responses

- `default`: Error

---

[API](https://skmtc.dev/castpdf/apis/castpdf-api.md) · [All operations](https://skmtc.dev/castpdf/apis/castpdf-api/llms.txt) · [OpenAPI document](https://skmtc.dev/castpdf/apis/castpdf-api/revisions/4ec737ba2ba6?raw)