Async Conversions

For long-running conversions or when you do not want to block your server, use the async conversion endpoint. Submit a job, then poll for the result or receive a webhook notification when it completes.

Submit an Async Job

POST https://api.pdfrelay.com/v1/convert/async

The request body is identical to the synchronous /v1/convert endpoint, with an optional webhook_url field:

curl -X POST https://api.pdfrelay.com/v1/convert/async \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<h1>Large Report</h1><p>Lots of content...</p>",
    "options": { "page_size": "A4" },
    "webhook_url": "https://your-app.com/webhooks/pdfrelay"
  }'

Response:

{
  "success": true,
  "data": {
    "job_id": "job_abc123def456",
    "status": "pending",
    "created_at": "2025-01-15T10:30:00Z"
  }
}

Polling for Status

Check the status of an async job by polling the job endpoint:

GET https://api.pdfrelay.com/v1/jobs/:job_id

curl https://api.pdfrelay.com/v1/jobs/job_abc123def456 \
  -H "Authorization: Bearer sk_live_..."

Response when still processing:

{
  "success": true,
  "data": {
    "job_id": "job_abc123def456",
    "status": "processing",
    "created_at": "2025-01-15T10:30:00Z"
  }
}

Response when complete:

{
  "success": true,
  "data": {
    "job_id": "job_abc123def456",
    "status": "completed",
    "created_at": "2025-01-15T10:30:00Z",
    "completed_at": "2025-01-15T10:30:02Z",
    "download_url": "https://api.pdfrelay.com/v1/jobs/job_abc123def456/download",
    "pages": 3,
    "size_bytes": 45678
  }
}

Job Statuses

Status	Description
`pending`	Job is queued and waiting to be processed
`processing`	Job is currently being converted
`completed`	Conversion finished successfully, download URL available
`failed`	Conversion failed, error details included in response

Webhook Notifications

Instead of polling, provide a webhook_url when creating the async job. pdfRelay will send a POST request to your URL when the job completes or fails.

See the Webhooks documentation for details on payload format, signature verification, and retry behavior.

Best Practices

Use webhooks over polling when possible. They are more efficient and provide immediate notification.
If polling, use exponential backoff. Start at 1 second, double the interval up to a maximum of 30 seconds.
Download URLs expire after 24 hours. Download the PDF or use document hosting for long-term storage.
Use async for documents over 10 pages or with complex layouts to avoid HTTP timeouts.