Skip to main content
POST
/
api
/
v1
/
templates
/
{templateId}
/
generate-async
Generate PDF (async)
curl --request POST \
  --url https://pdfgorilla.io/api/v1/templates/{templateId}/generate-async \
  --header 'Content-Type: <content-type>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "data": {},
  "jsonData": "<string>",
  "webhookUrl": "<string>",
  "webhookSecret": "<string>",
  "idempotencyKey": "<string>"
}
'
{
  "jobId": "<string>",
  "status": "<string>",
  "deduplicated": true
}
Creates a background job and returns immediately with 202 and a jobId. Then use Get job status, Download job PDF, or Cancel job.

​
Request

​
Path parameters

​
templateId
string
required
ID of your template.

​
Headers

​
x-api-key
string
required
Your API key, or Authorization: Bearer <key>.
​
Content-Type
string
required
application/json

​
Body

​
data
object
Data merged into the template (plain JSON object).
​
jsonData
string
Same as data, but a JSON-encoded string. Use one or the other (not both required; if both are sent, jsonData takes precedence).
​
webhookUrl
string
HTTPS URL called when the job reaches a terminal state (completed, failed, canceled). Must be public (not localhost).
​
webhookSecret
string
Required when webhookUrl is set. Used to sign the webhook body. Max length: 512 chars. See Webhooks.
​
idempotencyKey
string
Stable key you choose. If you retry the same request, an existing job with this key is returned and deduplicated: true.

​
Response

​
HTTP 202: Job created

{
  "jobId": "cma1b2c3d4e5f6g7h8i9j0k",
  "status": "queued",
  "deduplicated": false
}
​
jobId
string
Use this with GET /api/v1/jobs/{jobId}.
​
status
string
Usually "queued" for a new job. If deduplicated is true, this can be any existing job status.
​
deduplicated
boolean
true when an existing job was reused for the same idempotencyKey.

​
Error responses

StatusTypical cause
400Invalid body, webhook URL, or missing webhookSecret with webhookUrl
401Auth failed
404Template not found
413Request too large
422Data/template validation exceeded a complexity limit
429Rate limit, page quota, or too many active jobs
500Internal server error

​
Examples

curl -X POST https://pdfgorilla.io/api/v1/templates/TEMPLATE_ID/generate-async \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"data": {"orderId": "A-1"}}'

​
Job lifecycle (text)

queued -> processing -> completed
                    -> failed
                    -> canceled
                    -> expired (after retention)
Details: Get job status, Async workflow.

​
Rate limits

LimitValue
New async jobs per minute (per identity subject)20
Additional generate-rate check for API-key requests60 per minute
Active jobs per account10
Active jobs per API key20
See Limits.