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

# Create a batch

`POST /batches`

## Request

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

Creates a new batch in the API key's workspace. The `designId`
and (optional) `emailTemplateId` must already exist in the same
workspace; create them from the web app first.

## Request body

- BatchInput
  - `title` string, required
  - `description` string, nullable
  - `designId` string, required: Must refer to a design in the same workspace as the API key.
  - `emailTemplateId` string, nullable: Must refer to an email template in the same workspace.
  - `courseName` string, nullable
  - `issuerName` string, nullable

## Response `201`

The created batch.

- object
  - `batch` Batch, required
    - `id` string, required
    - `workspaceId` string, required
    - `title` string, required
    - `description` string, nullable
    - `designId` string, required
    - `emailTemplateId` string, nullable
    - `courseName` string, nullable: Default `{{course_name}}` for recipients in this batch.
    - `issuerName` string, nullable: Default `{{issuer_name}}` for recipients in this batch.
    - `recipientCount` integer, required: Cached count of recipients in the batch.
    - `archivedAt` string, date-time, nullable, required: Soft-delete marker. `null` for active batches; set when the batch has been archived via `POST /batches/{id}/archive`. Archived batches still serve `GET /batches/{id}`, public certificate URLs, and certificate lookups — but every write endpoint (recipient create / update / delete / send) returns `409 BATCH_ARCHIVED` until the batch is unarchived.
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required

## Other responses

- `400`: The request body or query was invalid.
- `401`: Missing, malformed, expired, or revoked API key.
- `402`: Plan quota exhausted (`QUOTA_EXCEEDED`) or a non-period plan limit was hit (`PLAN_LIMIT_EXCEEDED`, e.g. `maxBatches`). Upgrade the plan to lift the limit.
- `429`: Too many requests for this API key. Honour the `Retry-After` response header (seconds) or the `detail.retryAfter` field.

---

[API](https://skmtc.dev/certseal/apis/certseal-com-api.md) · [All operations](https://skmtc.dev/certseal/apis/certseal-com-api/llms.txt) · [OpenAPI document](https://skmtc.dev/certseal/apis/certseal-com-api/revisions/9097f49f49f5?raw)