Why Is My PDFMonkey Download URL Empty or Null?

Last updated March 23, 2026

The download_url field is null whenever a document has not reached the success status. This page walks through each cause and how to fix it.

The document status is “draft”

This is the most common cause. If you do not set a status attribute when creating your document, it defaults to draft and no generation takes place. Since the document is never generated, there is no file to download and download_url stays null.

How to fix it

Set "status": "pending" when you create the document to queue generation immediately:

{
  "document": {
    "document_template_id": "YOUR_TEMPLATE_ID",
    "status": "pending",
    "payload": {
      "name": "Jane Doe"
    }
  }
}

You can also update an existing draft document by sending a PATCH request with "status": "pending". See the Documents API reference for details.

Setting "status": "pending" at creation time is the most common pattern for API integrations. It skips the draft step entirely and queues generation in a single request.

The document status is “pending” or “generating”

If you set "status": "pending" when creating the document, generation is queued but may not be finished yet. The API response to your creation request returns the document in pending or generating status; the download_url is null at this point because the file does not exist yet.

How to fix it

Wait for generation to complete before reading the URL. You have three options:

ApproachHow it worksBest for
WebhookPDFMonkey sends a POST to your endpoint when the document reaches success or failure.Production integrations
PollingFetch the document in a loop until status is success or failure.Simple scripts, prototyping
Sync endpointPOST /api/v1/documents/sync creates the document and waits for the result in a single request (6-minute timeout).Low-volume, latency-tolerant workflows

See Webhooks and Synchronous Generation for setup instructions.

The document status is “failure”

If generation failed, the document status is failure and download_url is null. The failure_cause field contains a human-readable error message, and generation_logs provides additional detail.

How to fix it

  1. Inspect the failure_cause and generation_logs fields in the API response.
  2. Fix the underlying issue in your template or payload.
  3. Retry generation by setting the document status back to "pending" via a PATCH request.

See Document Statuses and Lifecycle for common failure causes.

Don’t confuse download_url with preview_url

preview_url is not a download link

The preview_url field renders a visual preview of the document in the browser. It works even for drafts and does not trigger a file download. If you need the generated file, use download_url instead.

A good example of preview_url in action is the PDFMonkey Dashboard itself: when you create a document, the preview panel on the right uses preview_url to show what the output looks like before you generate it.

See Embedding a Document Preview to learn how to use preview_url in your own application.

Frequently asked questions

I set status to “pending” but the download URL is still null.

The creation response returns the document before generation is complete. You need to wait for the status to reach success by polling the API, using a webhook, or using the sync endpoint.

How long does generation take?

Most documents are generated within a few seconds. Complex templates with many pages, heavy images, or external assets can take longer. The sync endpoint has a 6-minute timeout.

Can I get the download URL without polling?

Yes. Set up a webhook endpoint to receive a notification when generation succeeds. The webhook payload includes the download_url. Alternatively, use the sync endpoint to wait for the result in a single request.

Frequently asked questions

Why is the PDFMonkey download URL empty or null?
The download_url field is null whenever the document has not reached the "success" status. The most common cause is forgetting to set status to "pending" when creating the document, which leaves it in "draft" and skips generation entirely. Set status to "pending", then poll for completion or use a webhook.
How do I get a download URL from PDFMonkey?
Create a document with status set to "pending" to queue generation. Once the status reaches "success", the download_url field contains a temporary signed URL valid for 1 hour. You can poll the API, use a webhook, or use the synchronous /api/v1/documents/sync endpoint.
Navigation