Document Statuses and Lifecycle

Every document in PDFMonkey moves through a series of statuses on its way from creation to final PDF. Understanding this lifecycle helps you build reliable integrations and troubleshoot generation issues.

Status overview

stateDiagram-v2
    [*] --> draft: Created via API or Dashboard
    draft --> pending: Generation requested
    pending --> generating: Picked up by worker
    generating --> success: PDF ready
    generating --> failure: Error occurred
    failure --> pending: Retry requested

Draft

A document starts in the draft status when you create it, whether through the API or the Dashboard. This is the default status – if you don’t set "status": "pending" in your API call, the document stays here.

What you can do:

• Edit the document’s dynamic data (payload)
• Preview the document using the preview_url field (see Embedding a Document Preview)
• Delete the document

Transition out: Request generation by calling the API with "status": "pending" or by clicking Generate in the Dashboard. The document moves to pending.

Pending

A document in the pending status is queued and waiting to be picked up by a generation worker.

What it means: The generation request has been accepted but processing has not started yet. Under normal conditions, documents leave this status within seconds.

Transition out: A worker picks up the document and moves it to generating. This happens automatically – no action is required on your end.

Generating

A document in the generating status is actively being processed. The template is rendered with the document’s payload and converted to a PDF (or image, depending on the template’s output format).

What it means: The worker is building the document. This typically takes a few seconds, but complex templates with many pages or heavy assets can take longer.

Transition out: The document moves to either success or failure depending on the outcome.

Success

A document in the success status has been generated and its PDF is available for download.

What you can do:

• Download the PDF via the download_url field – this is a temporary signed URL valid for 1 hour, refreshed on each API fetch (see The Download URL)
• Share the document via its public_share_link if enabled (see Share Links)
• Receive a webhook notification when generation completes

Failure

A document in the failure status encountered an error during generation. The failure_cause field in the API response contains a human-readable description of what went wrong. The generation_logs field provides additional detail for debugging.

Common causes:

• Syntax errors in the template (Liquid, HTML, or CSS)
• Invalid or missing dynamic data
• Asset loading failures (broken image URLs, unreachable external resources)
• Timeout due to excessive template complexity

What you can do:

• Inspect failure_cause and generation_logs to understand the error
• Fix the underlying issue in the template or payload
• Retry generation by setting the document status back to "pending" via the API

Transition out: When you request a retry, the document returns to pending and goes through the generation cycle again.

Reacting to status changes

You don’t need to poll the API in a loop to know when a document is ready. Set up a webhook endpoint to receive a notification when generation succeeds or fails. This is the recommended approach for production integrations.

If you prefer a synchronous workflow, use the /api/v1/documents/sync endpoint to wait for the result in a single request. See Synchronous Generation for details and caveats.

Related pages

• The Download URL – how temporary download links work
• Webhooks – receive notifications on status changes
• API Documents reference – full endpoint and field documentation
• Troubleshooting: The Download URL is Empty – common reasons why download_url is null
• Troubleshooting: The Download URL Gives a 403 Error – how to handle expired URLs

Frequently asked questions

What statuses can a PDFMonkey document have?

Documents move through five statuses: draft (created but not queued), pending (queued for processing), generating (actively being rendered), success (PDF is ready to download), and failure (an error occurred during generation).

Can I skip the draft status when generating a PDFMonkey document?

Yes. Set the status to pending when creating the document via the API to queue generation immediately. This is the most common pattern for API integrations.

What happens when a PDFMonkey document fails to generate?

The document moves to failure status with a failure_cause field describing the error. You can inspect the error, fix the template or payload issue, and retry by setting the status back to pending.