---
title: "Generate PDF asynchronously"
method: POST
path: "/v1/pdf/create-async"
tags: ["PDF Async"]
---

# Generate PDF asynchronously

`POST /v1/pdf/create-async`

Queue a PDF generation job for async processing.

**Authentication:** API Key required (`x-api-key` header)

## How It Works

1. Submit a job with template and data
2. Receive a `job_id` immediately
3. Poll `/v1/pdf/status/{job_id}` for completion
4. Optionally receive a webhook notification

## When to Use Async

Use async generation when:
- Processing large documents or batches
- You can't wait for synchronous response
- You want webhook notifications

## Webhooks

If `webhook_url` is provided, we'll POST to it when the job completes or fails:

```json
{
    "event": "pdf.completed",
    "job_id": "...",
    "status": "completed",
    "result": {
        "url": "https://...",
        "filename": "invoice.pdf"
    }
}
```

Webhooks include HMAC-SHA256 signature in `X-TemplateFox-Signature` header
if you provide a `webhook_secret`.

**Credits:** 1 credit deducted immediately (refunded if job fails permanently).

## Request body

- CreateAsyncPdfRequest — Request model for async PDF generation
  - `template_id` string, required — Template short ID (12 characters)
  - `data` object, required — Key-value data to render in the template.
  - `export_type` 'url' — PDF export type options for async generation
  - `expiration` integer — URL expiration in seconds (60-604800). Default: 86400 (24 hours).
  - `filename` string, nullable — Custom filename for the PDF (without .pdf extension).
  - `store_s3` boolean — Upload to your configured S3 bucket instead of CDN.
  - `s3_filepath` string, nullable — Custom path prefix in your S3 bucket.
  - `s3_bucket` string, nullable — Override the default bucket configured in your S3 integration.
  - `webhook_url` string, uri, nullable — URL to receive POST notification when job completes or fails. Must be a public HTTPS URL.
  - `webhook_secret` string, nullable — Secret for HMAC-SHA256 signing of webhook payloads (min 16 chars).
  - `pdf_variant` 'pdf/a-1b' | 'pdf/a-2b' | 'pdf/a-3b' — PDF variant for standards-compliant output (PDF/A).
  - `version` string, nullable — Optional version tag (e.g. `prod`) or version number (e.g. `3`). When omitted, uses the template's default version if set, otherwise the current draft.

## Response `200`

Job queued successfully

- CreateAsyncPdfResponse — Response for async PDF creation
  - `job_id` string, required — Unique job identifier for status polling
  - `status` 'pending' | 'processing' | 'completed' | 'failed', required — PDF job status values
  - `credits_remaining` integer, required — Remaining credits after this request

## Other responses

- `402` — Insufficient credits
- `403` — Access denied - not your template
- `404` — Template not found
- `422` — Validation Error
- `429` — Rate limit exceeded

---

[API](https://skmtc.net/pdftemplateapi/apis/templatefox-api.md) · [All operations](https://skmtc.net/pdftemplateapi/apis/templatefox-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pdftemplateapi/templatefox-api/revisions/5673fc0d5fad/schema)