Sign in

v1

latestOpenAPI 3.1.02026-08-06244570.4 KB
PDF Async

Generate PDF asynchronously

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:

{
    "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).

post/v1/pdf/create-async

Request body

template_idstring required

Template short ID (12 characters)

dataobject required

Key-value data to render in the template.

export_type'url'

PDF export type options for async generation

expirationinteger

URL expiration in seconds (60-604800). Default: 86400 (24 hours).

filenamestring nullable

Custom filename for the PDF (without .pdf extension).

store_s3boolean

Upload to your configured S3 bucket instead of CDN.

s3_filepathstring nullable

Custom path prefix in your S3 bucket.

s3_bucketstring nullable

Override the default bucket configured in your S3 integration.

webhook_urlstring uri nullable

URL to receive POST notification when job completes or fails. Must be a public HTTPS URL.

webhook_secretstring 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).

versionstring 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.

Example request

{
  "data": {
    "invoice_number": "INV-001",
    "name": "John Doe"
  },
  "expiration": 86400,
  "export_type": "url",
  "filename": "invoice-001",
  "template_id": "HMQywVpZxqAM",
  "webhook_url": "https://example.com/webhooks/pdf"
}

Response

Job queued successfully

job_idstring required

Unique job identifier for status polling

status'pending' | 'processing' | 'completed' | 'failed' required

PDF job status values

credits_remaininginteger required

Remaining credits after this request

Example response

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "credits_remaining": 99
}