Batch API

Convert up to 100 documents in a single API request. Ideal for generating invoices, reports, certificates, or any scenario where you need multiple PDFs at once.

Endpoint

POST https://api.pdfrelay.com/v1/batch

Request Body

Send an array of conversion items, each with its own HTML and optional configuration:

{
  "items": [
    {
      "id": "invoice-1001",
      "html": "<h1>Invoice #1001</h1><p>Amount: $99.00</p>",
      "options": { "page_size": "A4" }
    },
    {
      "id": "invoice-1002",
      "html": "<h1>Invoice #1002</h1><p>Amount: $149.00</p>",
      "options": { "page_size": "A4" }
    },
    {
      "id": "invoice-1003",
      "html": "<h1>Invoice #1003</h1><p>Amount: $59.00</p>"
    }
  ],
  "webhook_url": "https://your-app.com/webhooks/pdfrelay-batch"
}

The id field is optional but recommended. It lets you correlate results with your source data. If omitted, pdfRelay assigns an auto-generated ID.

Response

The batch endpoint always processes asynchronously. You receive a batch ID immediately:

{
  "success": true,
  "data": {
    "batch_id": "batch_xyz789",
    "status": "pending",
    "total_items": 3,
    "created_at": "2025-01-15T10:30:00Z"
  }
}

Polling Batch Status

GET https://api.pdfrelay.com/v1/batch/:batch_id

Response when all items are complete:

{
  "success": true,
  "data": {
    "batch_id": "batch_xyz789",
    "status": "completed",
    "total_items": 3,
    "completed_items": 3,
    "failed_items": 0,
    "created_at": "2025-01-15T10:30:00Z",
    "completed_at": "2025-01-15T10:30:05Z",
    "items": [
      {
        "id": "invoice-1001",
        "status": "completed",
        "download_url": "https://api.pdfrelay.com/v1/batch/batch_xyz789/items/invoice-1001/download",
        "pages": 1,
        "size_bytes": 12345
      },
      {
        "id": "invoice-1002",
        "status": "completed",
        "download_url": "https://api.pdfrelay.com/v1/batch/batch_xyz789/items/invoice-1002/download",
        "pages": 1,
        "size_bytes": 13456
      },
      {
        "id": "invoice-1003",
        "status": "completed",
        "download_url": "https://api.pdfrelay.com/v1/batch/batch_xyz789/items/invoice-1003/download",
        "pages": 1,
        "size_bytes": 11234
      }
    ]
  }
}

Limits and Best Practices

Limit	Value
Max items per batch	100
Max HTML size per item	5 MB
Max total request size	50 MB
Download URL expiry	24 hours

Each item in a batch counts as one conversion against your monthly quota.
Use unique IDs for each item so you can correlate results with your source records.
Items are processed in parallel. The order of completion may differ from the order of submission.
Individual item failures do not fail the batch. Check each item's status in the response.