Create PDF Async — Queued PDF Generation with Webhooks

Queue a PDF for rendering and receive the result later — either by polling a job endpoint or via a webhook notification. Best for large documents, batches, or any flow where you don’t want to hold open an HTTP connection until rendering completes.

POST https://api.templatefox.com/v1/pdf/create-async

Authentication: API key in x-api-key header. Credits: 1 credit deducted when the job is queued (refunded if the job fails permanently).

For immediate generation, use create-pdf instead.

How it works

1. POST /v1/pdf/create-async with your template_id and data — you immediately receive a job_id.
2. The job moves through pending → processing → completed or failed.
3. You get the result one of two ways (or both):
   • Polling — call GET /v1/pdf/jobs/{job_id} until status is completed or failed.
   • Webhook — pass a webhook_url in the request; we POST to it when the job resolves.

Both delivery mechanisms are supported simultaneously. A webhook is optional.

Submit a job

Minimum required

Field	Type	Description
template_id	string	The 12-character template ID.
data	object	Key-value pairs matching your template variables.

curl TypeScript Python Go PHP Ruby Java C#

Copy

curl -X POST https://api.templatefox.com/v1/pdf/create-async \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "template_id": "HMQywVpZxqAM",
  "data": {
    "customer_name": "John Doe",
    "invoice_number": "INV-001"
  },
  "webhook_url": "https://example.com/webhooks/pdf"
}'

const response = await fetch("https://api.templatefox.com/v1/pdf/create-async", {
method: "POST",
headers: {
  "x-api-key": "YOUR_API_KEY",
  "Content-Type": "application/json",
},
body: JSON.stringify({
  template_id: "HMQywVpZxqAM",
  data: {
    customer_name: "John Doe",
    invoice_number: "INV-001",
  },
  webhook_url: "https://example.com/webhooks/pdf",
}),
});

const { job_id } = await response.json();

import requests

response = requests.post(
  "https://api.templatefox.com/v1/pdf/create-async",
  headers={"x-api-key": "YOUR_API_KEY"},
  json={
      "template_id": "HMQywVpZxqAM",
      "data": {
          "customer_name": "John Doe",
          "invoice_number": "INV-001",
      },
      "webhook_url": "https://example.com/webhooks/pdf",
  },
)

print(response.json()["job_id"])

payload, _ := json.Marshal(map[string]any{
  "template_id": "HMQywVpZxqAM",
  "data": map[string]string{
      "customer_name":  "John Doe",
      "invoice_number": "INV-001",
  },
  "webhook_url": "https://example.com/webhooks/pdf",
})

req, _ := http.NewRequest("POST", "https://api.templatefox.com/v1/pdf/create-async", bytes.NewReader(payload))
req.Header.Set("x-api-key", "YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

<?php
$ch = curl_init('https://api.templatefox.com/v1/pdf/create-async');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
      'x-api-key: YOUR_API_KEY',
      'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
      'template_id' => 'HMQywVpZxqAM',
      'data' => [
          'customer_name'  => 'John Doe',
          'invoice_number' => 'INV-001',
      ],
      'webhook_url' => 'https://example.com/webhooks/pdf',
  ]),
]);

$response = json_decode(curl_exec($ch), true);
echo $response['job_id'];

require 'net/http'
require 'json'

uri = URI('https://api.templatefox.com/v1/pdf/create-async')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri, {
'x-api-key'    => 'YOUR_API_KEY',
'Content-Type' => 'application/json'
})
request.body = {
template_id: 'HMQywVpZxqAM',
data: {
  customer_name: 'John Doe',
  invoice_number: 'INV-001'
},
webhook_url: 'https://example.com/webhooks/pdf'
}.to_json

response = JSON.parse(http.request(request).body)
puts response['job_id']

var body = """
{
"template_id": "HMQywVpZxqAM",
"data": {
  "customer_name": "John Doe",
  "invoice_number": "INV-001"
},
"webhook_url": "https://example.com/webhooks/pdf"
}
""";

var request = HttpRequest.newBuilder()
  .uri(URI.create("https://api.templatefox.com/v1/pdf/create-async"))
  .header("x-api-key", "YOUR_API_KEY")
  .header("Content-Type", "application/json")
  .POST(HttpRequest.BodyPublishers.ofString(body))
  .build();

var response = HttpClient.newHttpClient()
  .send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

using System.Net.Http;
using System.Net.Http.Json;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY");

var response = await client.PostAsJsonAsync(
  "https://api.templatefox.com/v1/pdf/create-async",
  new {
      template_id = "HMQywVpZxqAM",
      data = new {
          customer_name = "John Doe",
          invoice_number = "INV-001"
      },
      webhook_url = "https://example.com/webhooks/pdf"
  }
);

Console.WriteLine(await response.Content.ReadAsStringAsync());

Or use one of our official SDKs — TypeScript, Python, Go, PHP, Ruby, Java, C#.

All parameters

Field	Type	Required	Default	Description
template_id	string	✅	—	12-character template ID.
data	object	✅	—	Key-value data merged into the template.
export_type	string	—	"url"	Currently "url" is the only supported value for async. Use create-pdf for binary responses.
expiration	integer	—	86400	Signed URL expiration in seconds (60–604800).
filename	string	—	"document"	Custom filename (no extension).
store_s3	boolean	—	false	Upload to your configured S3 bucket instead of our CDN.
s3_filepath	string	—	—	Path prefix inside your S3 bucket.
s3_bucket	string	—	—	Override the bucket name from your S3 integration.
webhook_url	string	—	—	Public HTTPS URL to notify on completion or failure.
webhook_secret	string	—	—	Secret (16–256 chars) used to HMAC-SHA256 sign webhook payloads.
pdf_variant	string	—	—	"pdf/a-1b", "pdf/a-2b", or "pdf/a-3b" for archival compliance.
version	string	—	—	Template version tag or number.

Example: signed webhook + S3 upload

A fully configured async request — webhook with HMAC signing, S3 upload, custom filename, PDF/A compliance.

curl TypeScript Python Go

Copy

curl -X POST https://api.templatefox.com/v1/pdf/create-async \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "template_id": "HMQywVpZxqAM",
  "data": { "invoice_number": "INV-001" },
  "filename": "invoice-001",
  "store_s3": true,
  "s3_filepath": "invoices/2026/04/",
  "pdf_variant": "pdf/a-2b",
  "webhook_url": "https://example.com/webhooks/pdf",
  "webhook_secret": "whk_a1b2c3d4e5f6g7h8i9j0k1l2"
}'

await fetch("https://api.templatefox.com/v1/pdf/create-async", {
method: "POST",
headers: {
  "x-api-key": "YOUR_API_KEY",
  "Content-Type": "application/json",
},
body: JSON.stringify({
  template_id: "HMQywVpZxqAM",
  data: { invoice_number: "INV-001" },
  filename: "invoice-001",             // no extension, .pdf appended
  store_s3: true,                      // upload to your S3 bucket
  s3_filepath: "invoices/2026/04/",    // key prefix
  pdf_variant: "pdf/a-2b",             // archival compliance
  webhook_url: "https://example.com/webhooks/pdf",
  webhook_secret: "whk_a1b2c3d4e5f6g7h8i9j0k1l2",
}),
});

import requests

requests.post(
  "https://api.templatefox.com/v1/pdf/create-async",
  headers={"x-api-key": "YOUR_API_KEY"},
  json={
      "template_id": "HMQywVpZxqAM",
      "data": {"invoice_number": "INV-001"},
      "filename": "invoice-001",             # no extension
      "store_s3": True,                      # upload to your S3 bucket
      "s3_filepath": "invoices/2026/04/",    # key prefix
      "pdf_variant": "pdf/a-2b",             # archival compliance
      "webhook_url": "https://example.com/webhooks/pdf",
      "webhook_secret": "whk_a1b2c3d4e5f6g7h8i9j0k1l2",
  },
)

payload, _ := json.Marshal(map[string]any{
  "template_id":    "HMQywVpZxqAM",
  "data":           map[string]string{"invoice_number": "INV-001"},
  "filename":       "invoice-001",
  "store_s3":       true,
  "s3_filepath":    "invoices/2026/04/",
  "pdf_variant":    "pdf/a-2b",
  "webhook_url":    "https://example.com/webhooks/pdf",
  "webhook_secret": "whk_a1b2c3d4e5f6g7h8i9j0k1l2",
})

req, _ := http.NewRequest("POST", "https://api.templatefox.com/v1/pdf/create-async", bytes.NewReader(payload))
req.Header.Set("x-api-key", "YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")
http.DefaultClient.Do(req)

When the job completes, the webhook payload will include result.s3_bucket and result.s3_key instead of result.url, and every request will carry an X-TemplateFox-Signature header — see Verifying the signature.

Response

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

Field	Type	Description
job_id	string	UUID to poll or correlate with webhook notifications.
status	string	Always "pending" at creation time.
credits_remaining	number	Credits left after deduction.

Poll job status

GET /v1/pdf/jobs/{job_id}

Get the current status of a job.

curl TypeScript Python Go PHP Ruby Java C#

Copy

curl https://api.templatefox.com/v1/pdf/jobs/550e8400-e29b-41d4-a716-446655440000 \
-H "x-api-key: YOUR_API_KEY"

const jobId = "550e8400-e29b-41d4-a716-446655440000";

let job;
while (true) {
const r = await fetch(`https://api.templatefox.com/v1/pdf/jobs/${jobId}`, {
  headers: { "x-api-key": "YOUR_API_KEY" },
});
job = await r.json();
if (job.status === "completed" || job.status === "failed") break;
await new Promise((res) => setTimeout(res, 2000));
}

console.log(job.result_url);

import time
import requests

job_id = "550e8400-e29b-41d4-a716-446655440000"

while True:
  r = requests.get(
      f"https://api.templatefox.com/v1/pdf/jobs/{job_id}",
      headers={"x-api-key": "YOUR_API_KEY"},
  ).json()
  if r["status"] in ("completed", "failed"):
      break
  time.sleep(2)

print(r.get("result_url"))

package main

import (
  "encoding/json"
  "fmt"
  "net/http"
  "time"
)

func main() {
  jobID := "550e8400-e29b-41d4-a716-446655440000"
  url := "https://api.templatefox.com/v1/pdf/jobs/" + jobID

  var job map[string]any
  for {
      req, _ := http.NewRequest("GET", url, nil)
      req.Header.Set("x-api-key", "YOUR_API_KEY")
      resp, _ := http.DefaultClient.Do(req)
      json.NewDecoder(resp.Body).Decode(&job)
      resp.Body.Close()

      status := job["status"].(string)
      if status == "completed" || status == "failed" {
          break
      }
      time.Sleep(2 * time.Second)
  }

  fmt.Println(job["result_url"])
}

<?php
$jobId = '550e8400-e29b-41d4-a716-446655440000';
$url = "https://api.templatefox.com/v1/pdf/jobs/{$jobId}";

while (true) {
  $ch = curl_init($url);
  curl_setopt_array($ch, [
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTPHEADER => ['x-api-key: YOUR_API_KEY'],
  ]);
  $job = json_decode(curl_exec($ch), true);
  curl_close($ch);

  if (in_array($job['status'], ['completed', 'failed'])) break;
  sleep(2);
}

echo $job['result_url'] ?? '';

require 'net/http'
require 'json'

job_id = '550e8400-e29b-41d4-a716-446655440000'
uri = URI("https://api.templatefox.com/v1/pdf/jobs/#{job_id}")

job = nil
loop do
req = Net::HTTP::Get.new(uri, { 'x-api-key' => 'YOUR_API_KEY' })
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
job = JSON.parse(http.request(req).body)
break if %w[completed failed].include?(job['status'])
sleep 2
end

puts job['result_url']

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

var jobId = "550e8400-e29b-41d4-a716-446655440000";
var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
  .uri(URI.create("https://api.templatefox.com/v1/pdf/jobs/" + jobId))
  .header("x-api-key", "YOUR_API_KEY")
  .GET()
  .build();

String body;
while (true) {
  body = client.send(request, HttpResponse.BodyHandlers.ofString()).body();
  if (body.contains("\"completed\"") || body.contains("\"failed\"")) break;
  Thread.sleep(2000);
}

System.out.println(body);

using System.Net.Http;
using System.Text.Json;

var jobId = "550e8400-e29b-41d4-a716-446655440000";
var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY");

JsonElement job;
while (true)
{
  var body = await client.GetStringAsync(
      $"https://api.templatefox.com/v1/pdf/jobs/{jobId}"
  );
  job = JsonDocument.Parse(body).RootElement;
  var status = job.GetProperty("status").GetString();
  if (status == "completed" || status == "failed") break;
  await Task.Delay(2000);
}

Console.WriteLine(job.GetProperty("result_url").GetString());

Status values

Status	Description
pending	Queued, waiting to be picked up by a worker.
processing	A worker is rendering the PDF.
completed	PDF is ready — check result_url or result_s3_bucket/result_s3_key.
failed	Rendering failed — check error_message and error_code. Credit is refunded.

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "template_id": "HMQywVpZxqAM",
  "export_type": "url",
  "filename": "invoice-001",
  "store_s3": false,
  "created_at": "2026-04-24T12:00:00Z",
  "updated_at": "2026-04-24T12:00:05Z",
  "completed_at": "2026-04-24T12:00:05Z",
  "result_url": "https://cdn.templatefox.com/generated/abc123/invoice-001.pdf",
  "result_filename": "invoice-001.pdf",
  "result_expires_at": "2026-04-25T12:00:05Z",
  "result_s3_bucket": null,
  "result_s3_key": null,
  "error_message": null,
  "error_code": null
}

Polling recommendations

• Every 1–2 seconds for small documents.
• Every 5–10 seconds for large documents or batches.
• Use exponential backoff if you expect many jobs in flight.
• When possible, prefer webhooks to avoid the polling overhead.

Webhooks

If you provide webhook_url, we POST to it once the job resolves — no polling needed.

Headers

Header	Value
Content-Type	application/json
User-Agent	TemplateFox-Webhook/1.0
X-TemplateFox-Event	pdf.completed or pdf.failed
X-TemplateFox-Timestamp	Unix epoch seconds
X-TemplateFox-Signature	sha256=<hex> — only when webhook_secret is set

Completion payload

{
  "event": "pdf.completed",
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "result": {
    "url": "https://cdn.templatefox.com/generated/abc123/invoice-001.pdf",
    "filename": "invoice-001.pdf"
  }
}

For S3 uploads, the result object contains s3_bucket and s3_key instead of url.

Failure payload

{
  "event": "pdf.failed",
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "error": {
    "message": "Template rendering failed: missing variable 'customer_name'",
    "code": "RENDER_ERROR"
  }
}

Verifying the signature

When a webhook_secret is set, we sign every webhook with HMAC-SHA256:

signature = HMAC_SHA256(secret, timestamp + "." + raw_body)

Compare it to the value of X-TemplateFox-Signature after the sha256= prefix. Using the raw request body (before JSON parsing) is important — any re-serialization will invalidate the signature.

Python TypeScript

Copy

import hmac
import hashlib

def verify_signature(secret: str, timestamp: str, raw_body: bytes, signature_header: str) -> bool:
  if not signature_header.startswith("sha256="):
      return False
  received = signature_header.removeprefix("sha256=")
  expected = hmac.new(
      secret.encode("utf-8"),
      f"{timestamp}.{raw_body.decode('utf-8')}".encode("utf-8"),
      hashlib.sha256,
  ).hexdigest()
  return hmac.compare_digest(received, expected)

import crypto from "node:crypto";

export function verifySignature(
secret: string,
timestamp: string,
rawBody: string,
signatureHeader: string,
): boolean {
if (!signatureHeader.startsWith("sha256=")) return false;
const received = signatureHeader.slice("sha256=".length);
const expected = crypto
  .createHmac("sha256", secret)
  .update(`${timestamp}.${rawBody}`)
  .digest("hex");
const a = Buffer.from(received, "hex");
const b = Buffer.from(expected, "hex");
return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Retries

We retry failed webhook deliveries up to 3 times with exponential backoff (1s, 5s, 30s):

• Retried on network errors and 5xx responses.
• Not retried on 4xx responses (your endpoint actively rejected the request).

Respond with a 2xx status code within a few seconds to acknowledge receipt.

List jobs

GET /v1/pdf/jobs

List jobs belonging to your team. Supports pagination and status filtering.

Query parameter	Type	Default	Description
limit	integer	20	Page size (max 100).
offset	integer	0	Skip this many results.
status	string	—	Filter by pending, processing, completed, or failed.

curl TypeScript Python Go PHP Ruby Java C#

Copy

curl "https://api.templatefox.com/v1/pdf/jobs?status=failed&limit=50" \
-H "x-api-key: YOUR_API_KEY"

const params = new URLSearchParams({ status: "failed", limit: "50" });
const res = await fetch(
`https://api.templatefox.com/v1/pdf/jobs?${params}`,
{ headers: { "x-api-key": "YOUR_API_KEY" } },
);
const { jobs, total } = await res.json();

import requests

res = requests.get(
  "https://api.templatefox.com/v1/pdf/jobs",
  headers={"x-api-key": "YOUR_API_KEY"},
  params={"status": "failed", "limit": 50},
).json()

print(res["total"], len(res["jobs"]))

req, _ := http.NewRequest("GET",
  "https://api.templatefox.com/v1/pdf/jobs?status=failed&limit=50", nil)
req.Header.Set("x-api-key", "YOUR_API_KEY")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result struct {
  Jobs  []map[string]any `json:"jobs"`
  Total int              `json:"total"`
}
json.NewDecoder(resp.Body).Decode(&result)

<?php
$ch = curl_init('https://api.templatefox.com/v1/pdf/jobs?status=failed&limit=50');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['x-api-key: YOUR_API_KEY'],
]);

$result = json_decode(curl_exec($ch), true);
echo "Total: {$result['total']}";

require 'net/http'
require 'json'

uri = URI('https://api.templatefox.com/v1/pdf/jobs')
uri.query = URI.encode_www_form(status: 'failed', limit: 50)

req = Net::HTTP::Get.new(uri, { 'x-api-key' => 'YOUR_API_KEY' })
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

result = JSON.parse(http.request(req).body)
puts result['total']

var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
  .uri(URI.create("https://api.templatefox.com/v1/pdf/jobs?status=failed&limit=50"))
  .header("x-api-key", "YOUR_API_KEY")
  .GET()
  .build();

var response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

using System.Net.Http;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY");

var body = await client.GetStringAsync(
  "https://api.templatefox.com/v1/pdf/jobs?status=failed&limit=50"
);
Console.WriteLine(body);

Response

{
  "jobs": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "failed",
      "template_id": "HMQywVpZxqAM",
      "export_type": "url",
      "created_at": "2026-04-24T12:00:00Z",
      "error_message": "Template rendering failed",
      "error_code": "RENDER_ERROR"
    }
  ],
  "total": 3,
  "limit": 50,
  "offset": 0
}

When to use async vs sync

Use create-pdf (sync)	Use create-pdf-async
Short documents, simple data	Large documents or heavy rendering
Interactive request/response flow	Batch or background jobs
You need binary bytes directly	You want webhook callbacks
Low-volume, single-PDF requests	High-volume parallel generation