# Why Is My PDFMonkey Download URL Empty or Null?


The `download_url` field is `null` whenever a document has not reached the `success` [status](../generating-documents/document-statuses.md). This page walks through each cause and how to fix it.

## The document status is "draft" {#status-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 {#fix-status-draft}

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

```json
{
  "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](../api/documents.md) for details.

> [!TIP]
> 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" {#status-pending-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 {#fix-status-pending}

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

| Approach          | How it works                                                                                                        | Best for                               |
| :---------------- | :------------------------------------------------------------------------------------------------------------------ | :------------------------------------- |
| **Webhook**       | PDFMonkey sends a POST to your endpoint when the document reaches `success` or `failure`.                           | Production integrations                |
| **Polling**       | Fetch the document in a loop until `status` is `success` or `failure`.                                              | Simple scripts, prototyping            |
| **Sync endpoint** | `POST /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](../generating-documents/webhooks.md) and [Synchronous Generation](../api/documents.md#synchronous-generation) for setup instructions.

## The document status is "failure" {#status-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 {#fix-status-failure}

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](../generating-documents/document-statuses.md#failure) for common failure causes.

## Don't confuse download_url with preview_url {#preview-url-is-not-download}

> [!WARNING]
> **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](../generating-documents/embedding-a-preview.md) to learn how to use `preview_url` in your own application.


## Frequently asked questions {#faq}

**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](../api/documents.md#synchronous-generation).

**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](../generating-documents/webhooks.md) to receive a notification when generation succeeds. The webhook payload includes the `download_url`. Alternatively, use the [sync endpoint](../api/documents.md#synchronous-generation) to wait for the result in a single request.

## Related pages {#related-pages}

- [Document Statuses and Lifecycle](../generating-documents/document-statuses.md) — understand the draft, pending, generating, success, and failure statuses
- [Download URL](../generating-documents/download-url.md) — how temporary signed URLs work and when they expire
- [Generate Documents with the API](../generating-documents/api-pdf-generation.md) — end-to-end guide to creating documents via the API
- [Webhooks](../generating-documents/webhooks.md) — receive notifications when generation completes
- [Synchronous Generation](../api/documents.md#synchronous-generation) — create and wait for the result in one request
- [The Download URL Gives a 403 Error](../troubleshooting/download-url-gives-403.md) — how to handle expired URLs


## FAQ

**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.
