# Generate PDFs with the API


The PDFMonkey REST API lets you generate PDF documents from your templates by sending HTTP requests with JSON data. Use it to create invoices, receipts, reports, certificates, and any PDF from dynamic data -- this is the best approach for automated workflows in your own application.

> [!NOTE]
> **Prerequisites**
>
> You'll need a [PDFMonkey account](https://dashboard.pdfmonkey.io/users/sign_up) and at least one template. If you haven't created a template yet, see [From Zero to First Document](../getting-started/from-zero-to-first-document.md).


## Generate a PDF

### 1. Get your API key

Grab your secret key from the [API Key page](https://dashboard.pdfmonkey.io/api_key) in your dashboard. See [Authentication](../api/authentication.md) for details.

### 2. Create a document

Send a POST request to `/api/v1/documents` with your template ID and dynamic data. Setting `"status": "pending"` queues generation immediately.

Examples are available in curl, Ruby, Node.js, Python, and PHP:








**curl**

```bash
curl https://api.pdfmonkey.io/api/v1/documents \
  -X POST \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "document": {
      "document_template_id": "YOUR-TEMPLATE-ID",
      "status": "pending",
      "payload": {
        "name": "Jane Doe"
      }
    }
  }'
```

**Ruby**

```ruby
# generate! waits for the PDF to be ready before returning
document = Pdfmonkey::Document.generate!(
  document_template_id: 'YOUR-TEMPLATE-ID',
  payload: { name: 'Jane Doe' }
)

document.status       # => 'success'
document.download_url # => 'https://…'
```

**Node.js**

```javascript
const response = await fetch("https://api.pdfmonkey.io/api/v1/documents", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_SECRET_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    document: {
      document_template_id: "YOUR-TEMPLATE-ID",
      status: "pending",
      payload: { name: "Jane Doe" },
    },
  }),
});

const data = await response.json();
console.log(data.document);
```

**Python**

```python
import requests

response = requests.post(
    'https://api.pdfmonkey.io/api/v1/documents',
    headers={
        'Authorization': 'Bearer YOUR_SECRET_KEY',
    },
    json={
        'document': {
            'document_template_id': 'YOUR-TEMPLATE-ID',
            'status': 'pending',
            'payload': {'name': 'Jane Doe'},
        },
    },
)

print(response.json())
```

**PHP**

```php
<?php
$ch = curl_init('https://api.pdfmonkey.io/api/v1/documents');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_SECRET_KEY',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'document' => [
            'document_template_id' => 'YOUR-TEMPLATE-ID',
            'status' => 'pending',
            'payload' => ['name' => 'Jane Doe'],
        ],
    ]),
]);

$response = curl_exec($ch);
curl_close($ch);

print_r(json_decode($response, true));
```



The API returns the document with its current status. Note the `id` -- you'll need it to check on the generation.

```json title="201 Created (trimmed)"
{
  "document": {
    "id": "a5e86d72-f5b7-43d4-a04e-8b7e08e6741c",
    "status": "pending",
    "download_url": null,
    ...
  }
}
```

### 3. Check generation status

The PDF isn't ready yet -- poll the `document_cards` endpoint until the status reaches `success`, then read the `download_url`.








**curl**

```bash
curl -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  https://api.pdfmonkey.io/api/v1/document_cards/DOCUMENT_ID
# Once status is "success", the download_url field contains a signed link to the PDF
```

**Ruby**

```ruby
# Not needed if you used generate! above — the document is already ready
card = Pdfmonkey::Document.fetch_card('DOCUMENT_ID')

card.status       # => 'success'
card.download_url # => 'https://…'
```

**Node.js**

```javascript
const response = await fetch("https://api.pdfmonkey.io/api/v1/document_cards/DOCUMENT_ID", {
  headers: {
    Authorization: "Bearer YOUR_SECRET_KEY",
  },
});

const data = await response.json();
console.log(data.document_card.status); // => 'success'
console.log(data.document_card.download_url); // => 'https://…'
```

**Python**

```python
import requests

response = requests.get(
    'https://api.pdfmonkey.io/api/v1/document_cards/DOCUMENT_ID',
    headers={
        'Authorization': 'Bearer YOUR_SECRET_KEY',
    },
)

card = response.json()['document_card']
print(card['status'])       # => 'success'
print(card['download_url']) # => 'https://…'
```

**PHP**

```php
<?php
$ch = curl_init('https://api.pdfmonkey.io/api/v1/document_cards/DOCUMENT_ID');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_SECRET_KEY',
    ],
]);

$response = curl_exec($ch);
curl_close($ch);

$card = json_decode($response, true)['document_card'];
echo $card['status'];       // => 'success'
echo $card['download_url']; // => 'https://…'
```



> [!TIP]
> Instead of polling, you can set up a [webhook](./webhooks.md) to be notified when the document is ready. This is recommended for production workloads.


## Asynchronous vs synchronous generation

By default, document generation is **asynchronous**: you create the document, then either poll the API or set up a [webhook](./webhooks.md) to know when it is ready. This is the best approach for production workloads, especially at high volume.

If you prefer to wait for the result in a single request, use the **synchronous** endpoint at `/api/v1/documents/sync`. This is convenient for prototyping or low-volume, interactive use cases. See [Synchronous Generation](../api/documents.md#synchronous-generation) for details and caveats.

## Frequently asked questions

**What format should the payload use?**

The `payload` field accepts any valid JSON object. Its structure must match the variables used in your template -- see [Defining Dynamic Data](../code-templates/defining-dynamic-data.md).

**How long does PDF generation take?**

Most documents are ready within a few seconds. Complex templates with many pages or large images may take longer. Use a [webhook](./webhooks.md) to be notified as soon as the PDF is available.

**Is there a rate limit?**

There is no hard rate limit on the API, but your plan's monthly document quota applies. See [Our Plans](../pricing-and-billing/our-plans.md) for quota details.

**Can I generate multiple PDFs in one request?**

Not directly -- each API call generates one document. To generate PDFs in bulk, send multiple requests in parallel or use an automation platform like [Zapier](../integrations/zapier.md) or [Make](../integrations/make.md).

---

- [API Documents reference](../api/documents.md) -- full endpoint documentation
- [Document Statuses and Lifecycle](./document-statuses.md) -- understand document statuses
- [The Download URL](./download-url.md) -- how to retrieve the generated PDF
