Create Bulk Request

Batch dispatch independent signing requests across common templates, up to 100 per batch.

Authentication

This endpoint requires a bearer token. See Authentication and API Keys.

Headers

Header	Required	Description
Authorization	required	`Bearer <BEARER_TOKEN>`
Content-Type	required	`application/json`
Idempotency-Key	optional	A unique key for the batch operation. Reuse it when retrying the same batch. See Idempotency.

Parameters

This endpoint takes no query or path parameters.

Request body

Field	Required	Type	Description
templates	required	array	Array of template UUID strings shared by the batch.
requests	required	array	Array of recipient sets, up to 100. Each entry produces one signing request.
requests[].signers	required	array	Array of `{"name": "...", "email": "..."}` objects for that request.
mode	optional	string	`email` (default, auto-sends links) or `local` (retrieve links via API).
message	optional	string	Custom invitation email body. Defaults to `Please review and sign these documents.`

Request example

curl -X POST "https://toolkit.undersign.app/api/v1.1/bulk-signature-requests" \
  -H "Authorization: Bearer <BEARER_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <UNIQUE_KEY>" \
  -d '{
    "templates": ["<template-uuid>"],
    "requests": [
      { "signers": [{ "name": "Signer One", "email": "signer1@example.com" }] },
      { "signers": [{ "name": "Signer Two", "email": "signer2@example.com" }] }
    ],
    "mode": "email",
    "message": "Please review and complete this document."
  }'

Response

A successful batch returns 201 Created with the batch GUID and the package GUID of every created request. A processed batch decrements 1 API credit.

201 Created

{
  "success": true,
  "request_id": "...",
  "timestamp": "...",
  "data": {
    "bulk_batch_guid": "BULK-20260917-ABCDEF12",
    "package_guids": [
      "PKG01-ABCDE-12345",
      "PKG02-FGHIJ-67890"
    ]
  }
}

Response status & error codes

Code	Error code	Description
`201`	`-`	Batch processed. Decrements 1 API credit.
`400`	`VALIDATION_ERROR`	Empty `templates` or `requests` array.
`400`	`BATCH_SIZE_EXCEEDED`	`requests` array exceeds 100 items.
`400`	`SIGNER_COUNT_MISMATCH`	A request row has an incorrect number of signers.
`400`	`INVALID_SIGNER_DATA`	Missing name or email in a signer row.
`400`	`INVALID_EMAIL`	Invalid email format detected.
`403`	`CREDIT_LIMIT_REACHED`	Insufficient API credits. See Quotas & Credits.
`404`	`TEMPLATE_NOT_FOUND`	One or more template UUIDs do not exist.
`429`	`RATE_LIMIT_EXCEEDED`	Too many requests (limit: 100/min). See Rate Limits.

Create Signature Request

Send a single signing request.

Get Signature Request Status

Track each request via its package GUID.