How do I generate a document with the PDFMonkey API?

Send a POST request to /api/v1/documents with your template ID and dynamic data. Set status to "pending" to queue generation immediately. Then poll the document status or use webhooks to know when the file is ready to download.

What is the difference between Document and DocumentCard in PDFMonkey?

A Document is the full object including payload, generation_logs, and checksum. A DocumentCard is a lighter version without those fields but with document_template_identifier added. Use DocumentCards when you don't need the payload.

Does PDFMonkey support synchronous document generation?

Yes. POST to /api/v1/documents/sync to create a document and wait for the result in a single request. The endpoint has a 6-minute timeout and returns a DocumentCard.

How long is a PDFMonkey download URL valid?

Download URLs are temporary signed S3 URLs valid for 1 hour. After expiration, fetch the document again to get a fresh URL -- no need to regenerate.

Documents API: Create, List, and Manage Generated Documents

Complete API reference for creating, retrieving, updating, and deleting documents in PDFMonkey.

Quick start

Generation is asynchronous: you create a document, then check its status until it’s ready.

# 1. Create a document and queue it for generation
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" }
    }
  }'
# Returns a document with "status": "pending" and "download_url": null

# 2. Poll the document status until it reaches "success"
curl -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  https://api.pdfmonkey.io/api/v1/document_cards/DOCUMENT_ID
# Once status is "success", read the download_url from the response

Setting "status": "pending" queues the document for generation immediately. The file isn’t ready yet at this point — you need to poll the document or set up a webhook to know when it’s done. Once the status reaches success, the download_url field contains a signed link to the generated file.

Read on for the full details, including the synchronous endpoint that waits for the result in a single request.

Authentication

All requests require a Bearer token in the Authorization header:

Authorization: Bearer YOUR_SECRET_KEY

See Authentication for how to find your API key and manage access tokens.

Create a document

POST /api/v1/documents

Creates a new document. Set status to "pending" to queue generation immediately, or omit it (defaults to "draft") to generate later.

Parameters

All parameters are nested under a document key.

Name	Type	Required	Description
`document_template_id`	String (UUID)	Yes	ID of the template to use for generation.
`payload`	Object or String	No	The dynamic data used to build the document. Must be a JSON object (not an array). Can be passed as a JSON object or a JSON string.
`meta`	Object or String	No	Metadata to attach to the document. Supports special keys like `_filename`. Must be a JSON object. Max 200 KB.
`status`	String	No	`"draft"` (default) or `"pending"`. Set to `"pending"` to trigger generation on creation.

Set "status": "pending" in your create request to generate the document in one step. Without it, the document is created as a draft and you must update it later to trigger generation.

Request

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": "2903f5b4-623b-4e10-b2e3-dc7e2e67ea39",
      "status": "pending",
      "payload": {
        "clientName": "Peter Parker",
        "orderDate": "2050-03-14",
        "products": [
          { "name": "Spider silk", "quantity": 12, "unitPrice": 123.50 },
          { "name": "Spandex fabric", "quantity": 2, "unitPrice": 28.90 }
        ]
      },
      "meta": {
        "_filename": "2050-03-14 Peter Parker.pdf",
        "clientRef": "spidey-616"
      }
    }
  }'

document = Pdfmonkey::Document.generate(
  document_template_id: '2903f5b4-623b-4e10-b2e3-dc7e2e67ea39',
  payload: {
    clientName: 'Peter Parker',
    orderDate: '2050-03-14',
    products: [
      { name: 'Spider silk', quantity: 12, unitPrice: 123.50 },
      { name: 'Spandex fabric', quantity: 2, unitPrice: 28.90 }
    ]
  },
  meta: {
    _filename: '2050-03-14 Peter Parker.pdf',
    clientRef: 'spidey-616'
  }
)

document.status # => 'pending'

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: '2903f5b4-623b-4e10-b2e3-dc7e2e67ea39',
      status: 'pending',
      payload: {
        clientName: 'Peter Parker',
        orderDate: '2050-03-14',
        products: [
          { name: 'Spider silk', quantity: 12, unitPrice: 123.50 },
          { name: 'Spandex fabric', quantity: 2, unitPrice: 28.90 },
        ],
      },
      meta: {
        _filename: '2050-03-14 Peter Parker.pdf',
        clientRef: 'spidey-616',
      },
    },
  }),
});

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

import requests

response = requests.post(
    'https://api.pdfmonkey.io/api/v1/documents',
    headers={
        'Authorization': 'Bearer YOUR_SECRET_KEY',
    },
    json={
        'document': {
            'document_template_id': '2903f5b4-623b-4e10-b2e3-dc7e2e67ea39',
            'status': 'pending',
            'payload': {
                'clientName': 'Peter Parker',
                'orderDate': '2050-03-14',
                'products': [
                    {'name': 'Spider silk', 'quantity': 12, 'unitPrice': 123.50},
                    {'name': 'Spandex fabric', 'quantity': 2, 'unitPrice': 28.90},
                ],
            },
            'meta': {
                '_filename': '2050-03-14 Peter Parker.pdf',
                'clientRef': 'spidey-616',
            },
        },
    },
)

print(response.json())

<?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' => '2903f5b4-623b-4e10-b2e3-dc7e2e67ea39',
            'status' => 'pending',
            'payload' => [
                'clientName' => 'Peter Parker',
                'orderDate' => '2050-03-14',
                'products' => [
                    ['name' => 'Spider silk', 'quantity' => 12, 'unitPrice' => 123.50],
                    ['name' => 'Spandex fabric', 'quantity' => 2, 'unitPrice' => 28.90],
                ],
            ],
            'meta' => [
                '_filename' => '2050-03-14 Peter Parker.pdf',
                'clientRef' => 'spidey-616',
            ],
        ],
    ]),
]);

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

echo $response;

Response

{
  "document": {
    "id": "a5e86d72-f5b7-43d4-a04e-8b7e08e6741c",
    "app_id": "d6b4e8f2-7a3c-4d1e-9f5b-2c8a1d3e6f90",
    "checksum": "c230530f6f0aa32900af0924cf228e5c",
    "created_at": "2050-03-13T12:34:56.181+02:00",
    "document_template_id": "2903f5b4-623b-4e10-b2e3-dc7e2e67ea39",
    "download_url": null,
    "failure_cause": null,
    "filename": null,
    "generation_logs": [],
    "meta": {
      "_filename": "2050-03-14 Peter Parker.pdf",
      "clientRef": "spidey-616"
    },
    "output_type": "pdf",
    "payload": {
      "clientName": "Peter Parker",
      "orderDate": "2050-03-14",
      "products": [
        { "name": "Spider silk", "quantity": 12, "unitPrice": 123.50 },
        { "name": "Spandex fabric", "quantity": 2, "unitPrice": 28.90 }
      ]
    },
    "preview_url": "https://preview.pdfmonkey.io/pdf/web/viewer.html?file=...",
    "public_share_link": null,
    "status": "pending",
    "updated_at": "2050-03-13T12:34:56.181+02:00"
  }
}

Validation errors

If required fields are missing or invalid, the API returns a 422 Unprocessable Entity:

{
  "errors": {
    "document_template_id": ["can't be blank"]
  }
}

Synchronous generation

POST /api/v1/documents/sync

A convenience wrapper that creates a document and polls for completion server-side, so you get the finished result in a single request. The response is a DocumentCard (not a Document). For a guided walkthrough, see Generate Documents with the API.

This endpoint accepts the same parameters as Create a document. You must set "status": "pending" for generation to start.

When to use sync vs async

	Async	Sync
Response	Returns immediately	Waits until generation completes
Getting the result	Poll or use webhooks	Included in the response
Response object	Document	DocumentCard
Scales to high volume	Yes	No — one open request per document
Timeout	None	6 minutes
Best for	Production pipelines, batch generation	Low-volume or interactive use cases

The sync endpoint will wait up to 6 minutes for generation to complete. For production pipelines or batch generation, prefer async generation with webhooks.

Request

curl https://api.pdfmonkey.io/api/v1/documents/sync \
  -X POST \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "document": {
      "document_template_id": "2903f5b4-623b-4e10-b2e3-dc7e2e67ea39",
      "status": "pending",
      "payload": {
        "clientName": "Peter Parker",
        "orderDate": "2050-03-14",
        "products": [
          { "name": "Spider silk", "quantity": 12, "unitPrice": 123.50 },
          { "name": "Spandex fabric", "quantity": 2, "unitPrice": 28.90 }
        ]
      },
      "meta": {
        "_filename": "2050-03-14 Peter Parker.pdf",
        "clientRef": "spidey-616"
      }
    }
  }'

document = Pdfmonkey::Document.generate!(
  document_template_id: '2903f5b4-623b-4e10-b2e3-dc7e2e67ea39',
  payload: {
    clientName: 'Peter Parker',
    orderDate: '2050-03-14',
    products: [
      { name: 'Spider silk', quantity: 12, unitPrice: 123.50 },
      { name: 'Spandex fabric', quantity: 2, unitPrice: 28.90 }
    ]
  },
  meta: {
    _filename: '2050-03-14 Peter Parker.pdf',
    clientRef: 'spidey-616'
  }
)

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

const response = await fetch('https://api.pdfmonkey.io/api/v1/documents/sync', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_SECRET_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    document: {
      document_template_id: '2903f5b4-623b-4e10-b2e3-dc7e2e67ea39',
      status: 'pending',
      payload: {
        clientName: 'Peter Parker',
        orderDate: '2050-03-14',
        products: [
          { name: 'Spider silk', quantity: 12, unitPrice: 123.50 },
          { name: 'Spandex fabric', quantity: 2, unitPrice: 28.90 },
        ],
      },
      meta: {
        _filename: '2050-03-14 Peter Parker.pdf',
        clientRef: 'spidey-616',
      },
    },
  }),
});

const data = await response.json();
console.log(data.document_card.download_url);

import requests

response = requests.post(
    'https://api.pdfmonkey.io/api/v1/documents/sync',
    headers={
        'Authorization': 'Bearer YOUR_SECRET_KEY',
    },
    json={
        'document': {
            'document_template_id': '2903f5b4-623b-4e10-b2e3-dc7e2e67ea39',
            'status': 'pending',
            'payload': {
                'clientName': 'Peter Parker',
                'orderDate': '2050-03-14',
                'products': [
                    {'name': 'Spider silk', 'quantity': 12, 'unitPrice': 123.50},
                    {'name': 'Spandex fabric', 'quantity': 2, 'unitPrice': 28.90},
                ],
            },
            'meta': {
                '_filename': '2050-03-14 Peter Parker.pdf',
                'clientRef': 'spidey-616',
            },
        },
    },
    timeout=400,
)

data = response.json()
print(data['document_card']['download_url'])

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

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_TIMEOUT => 400,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_SECRET_KEY',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'document' => [
            'document_template_id' => '2903f5b4-623b-4e10-b2e3-dc7e2e67ea39',
            'status' => 'pending',
            'payload' => [
                'clientName' => 'Peter Parker',
                'orderDate' => '2050-03-14',
                'products' => [
                    ['name' => 'Spider silk', 'quantity' => 12, 'unitPrice' => 123.50],
                    ['name' => 'Spandex fabric', 'quantity' => 2, 'unitPrice' => 28.90],
                ],
            ],
            'meta' => [
                '_filename' => '2050-03-14 Peter Parker.pdf',
                'clientRef' => 'spidey-616',
            ],
        ],
    ]),
]);

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

$data = json_decode($response, true);
echo $data['document_card']['download_url'];

Response

The sync endpoint returns a DocumentCard, not a Document. The result is nested under document_card and does not include payload or generation_logs.

{
  "document_card": {
    "app_id": "d6b4e8f2-7a3c-4d1e-9f5b-2c8a1d3e6f90",
    "created_at": "2050-03-13T12:34:56.181+02:00",
    "document_template_id": "2903f5b4-623b-4e10-b2e3-dc7e2e67ea39",
    "document_template_identifier": "My Invoice Template",
    "download_url": "https://pdfmonkey.s3.eu-west-1.amazonaws.com/production/backend/document/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c/2050-03-14-peter-parker.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&...",
    "failure_cause": null,
    "filename": "2050-03-14 Peter Parker.pdf",
    "id": "a5e86d72-f5b7-43d4-a04e-8b7e08e6741c",
    "meta": {
      "_filename": "2050-03-14 Peter Parker.pdf",
      "clientRef": "spidey-616"
    },
    "output_type": "pdf",
    "preview_url": "https://preview.pdfmonkey.io/pdf/web/viewer.html?file=...",
    "public_share_link": null,
    "status": "success",
    "updated_at": "2050-03-13T12:34:59.412+02:00"
  }
}

The Document object

The Document object is the full representation of a generated document, including its payload and generation logs.

{
  "id": "a5e86d72-f5b7-43d4-a04e-8b7e08e6741c",
  "app_id": "d6b4e8f2-7a3c-4d1e-9f5b-2c8a1d3e6f90",
  "checksum": "c230530f6f0aa32900af0924cf228e5c",
  "created_at": "2050-03-13T12:34:56.181+02:00",
  "document_template_id": "2903f5b4-623b-4e10-b2e3-dc7e2e67ea39",
  "download_url": "https://pdfmonkey.s3.eu-west-1.amazonaws.com/production/backend/document/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c/2050-03-14-peter-parker.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&...",
  "failure_cause": null,
  "filename": "2050-03-14 Peter Parker.pdf",
  "generation_logs": [
    {
      "type": "info",
      "message": "Starting PDF generation.",
      "timestamp": "Thu, 13 Mar 2050 10:34:57 GMT"
    },
    {
      "type": "info",
      "message": "Generation took 1617ms to load and render.",
      "timestamp": "Thu, 13 Mar 2050 10:34:58 GMT"
    },
    {
      "type": "info",
      "message": "Content size is 96302.",
      "timestamp": "Thu, 13 Mar 2050 10:34:59 GMT"
    }
  ],
  "meta": {
    "_filename": "2050-03-14 Peter Parker.pdf",
    "clientRef": "spidey-616"
  },
  "output_type": "pdf",
  "payload": {
    "clientName": "Peter Parker",
    "orderDate": "2050-03-14",
    "products": [
      { "name": "Spider silk", "quantity": 12, "unitPrice": 123.50 },
      { "name": "Spandex fabric", "quantity": 2, "unitPrice": 28.90 }
    ]
  },
  "preview_url": "https://preview.pdfmonkey.io/pdf/web/viewer.html?file=...",
  "public_share_link": "https://files.pdfmonkey.io/share/72BE2293-D130-4C19-9E11-C82B5CEA8C37/2050-03-14-peter-parker.pdf",
  "status": "success",
  "updated_at": "2050-03-13T12:34:59.412+02:00"
}

Attributes

Name	Type	Description
`id`	String (UUID)	Unique identifier for the document.
`app_id`	String (UUID)	Unique identifier of the document’s workspace.
`checksum`	String	Internal checksum used for preview rendering.
`created_at`	String (ISO 8601)	Timestamp when the document was created.
`document_template_id`	String (UUID)	ID of the template used to generate this document.
`download_url`	String (URL) or `null`	Temporary signed URL to download the generated file. `null` until generation succeeds. Valid for 1 hour (see Download URLs).
`failure_cause`	String or `null`	Reason for generation failure. `null` unless status is `failure`.
`filename`	String or `null`	Name of the generated file. `null` until generation succeeds. Controllable via the `_filename` meta key.
`generation_logs`	Array	Logs collected during generation. Each entry has `type` (`"info"` or `"error"`), `message`, and `timestamp`. Empty array before generation starts.
`meta`	Object or `null`	Arbitrary metadata attached to the document. Supports special keys like `_filename`. Also accessible in no-code integrations (Zapier, Make) where `payload` is not available.
`output_type`	String	Output format: `"pdf"` or `"image"`. Inherited from the template.
`payload`	Object or `null`	The dynamic data used to generate the document.
`preview_url`	String (URL)	URL for embedding a visual preview of the document. Intended for use in an `<iframe>`, not for downloading.
`public_share_link`	String (URL) or `null`	Permanent public link to the generated file. Only available when the Share Links feature is enabled (Pro+ plans).
`status`	String	Current status of the document: `draft`, `pending`, `generating`, `success`, or `failure`. See Document Statuses and Lifecycle.
`updated_at`	String (ISO 8601)	Timestamp when the document was last updated.

The DocumentCard object

The DocumentCard is a lightweight version of the Document. It contains the same fields except payload, generation_logs, and checksum. It also adds document_template_identifier.

Use DocumentCards when you do not need the full payload, they are faster and lighter. They are the object returned by list endpoints, the sync endpoint, webhooks, and no-code integrations.

Prefer DocumentCard over Document.

Store any data you need later in meta instead of (or in addition to) payload. That way you will never need to fetch the full Document object.

{
  "id": "a5e86d72-f5b7-43d4-a04e-8b7e08e6741c",
  "app_id": "d6b4e8f2-7a3c-4d1e-9f5b-2c8a1d3e6f90",
  "created_at": "2050-03-13T12:34:56.181+02:00",
  "document_template_id": "2903f5b4-623b-4e10-b2e3-dc7e2e67ea39",
  "document_template_identifier": "My Invoice Template",
  "download_url": "https://pdfmonkey.s3.eu-west-1.amazonaws.com/production/backend/document/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c/2050-03-14-peter-parker.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&...",
  "failure_cause": null,
  "filename": "2050-03-14 Peter Parker.pdf",
  "meta": {
    "_filename": "2050-03-14 Peter Parker.pdf",
    "clientRef": "spidey-616"
  },
  "output_type": "pdf",
  "preview_url": "https://preview.pdfmonkey.io/pdf/web/viewer.html?file=...",
  "public_share_link": "https://files.pdfmonkey.io/share/72BE2293-D130-4C19-9E11-C82B5CEA8C37/2050-03-14-peter-parker.pdf",
  "status": "success",
  "updated_at": "2050-03-13T12:34:59.412+02:00"
}

Attributes

Name	Type	Description
`id`	String (UUID)	Unique identifier for the document.
`app_id`	String (UUID)	Unique identifier of the document’s workspace.
`created_at`	String (ISO 8601)	Timestamp when the document was created.
`document_template_id`	String (UUID)	ID of the template used to generate this document.
`document_template_identifier`	String	The name of the template as displayed in the dashboard.
`download_url`	String (URL) or `null`	Temporary signed URL to download the generated file. `null` until generation succeeds. Valid for 1 hour.
`failure_cause`	String or `null`	Reason for generation failure. `null` unless status is `failure`.
`filename`	String or `null`	Name of the generated file. `null` until generation succeeds.
`meta`	Object or `null`	Arbitrary metadata attached to the document.
`output_type`	String	Output format: `"pdf"` or `"image"`. Inherited from the template.
`preview_url`	String (URL)	URL for embedding a visual preview. Not for downloading.
`public_share_link`	String (URL) or `null`	Permanent public link. Requires Share Links (Pro+ plans).
`status`	String	Current status: `draft`, `pending`, `generating`, `success`, or `failure`.
`updated_at`	String (ISO 8601)	Timestamp when the document was last updated.

Comparison: Document vs DocumentCard

Field	Document	DocumentCard
`payload`	Included	Not included
`generation_logs`	Included	Not included
`checksum`	Included	Not included
`document_template_identifier`	Not included	Included

Get a document

Get a DocumentCard (recommended)

GET /api/v1/document_cards/{id}

Returns a DocumentCard for the given document. This is the recommended way to check generation status and retrieve the download URL.

curl -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  https://api.pdfmonkey.io/api/v1/document_cards/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c

card = Pdfmonkey::Document.fetch_card('a5e86d72-f5b7-43d4-a04e-8b7e08e6741c')

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

const response = await fetch(
  'https://api.pdfmonkey.io/api/v1/document_cards/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c',
  {
    headers: {
      'Authorization': 'Bearer YOUR_SECRET_KEY',
    },
  }
);

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

import requests

response = requests.get(
    'https://api.pdfmonkey.io/api/v1/document_cards/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c',
    headers={
        'Authorization': 'Bearer YOUR_SECRET_KEY',
    },
)

data = response.json()
print(data['document_card'])

<?php
$ch = curl_init('https://api.pdfmonkey.io/api/v1/document_cards/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c');

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

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

$data = json_decode($response, true);
print_r($data['document_card']);

Response: 200 OK with a document_card object.

Get a full Document

GET /api/v1/documents/{id}

Returns the full Document, including payload and generation_logs. Use this only when you need those fields.

curl -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  https://api.pdfmonkey.io/api/v1/documents/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c

document = Pdfmonkey::Document.fetch('a5e86d72-f5b7-43d4-a04e-8b7e08e6741c')

document.status   # => 'success'
document.payload  # => '{"clientName":"Peter Parker",…}'

const response = await fetch(
  'https://api.pdfmonkey.io/api/v1/documents/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c',
  {
    headers: {
      'Authorization': 'Bearer YOUR_SECRET_KEY',
    },
  }
);

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

import requests

response = requests.get(
    'https://api.pdfmonkey.io/api/v1/documents/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c',
    headers={
        'Authorization': 'Bearer YOUR_SECRET_KEY',
    },
)

data = response.json()
print(data['document'])

<?php
$ch = curl_init('https://api.pdfmonkey.io/api/v1/documents/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c');

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

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

$data = json_decode($response, true);
print_r($data['document']);

Response: 200 OK with a document object.

List documents

GET /api/v1/document_cards

Returns a paginated list of DocumentCards. Results are limited to 24 items per page.

Query parameters

Name	Type	Description
`page[number]`	Integer	Page number (default: `1`).
`q[document_template_id]`	String (UUID) or Array	Filter by one or more template IDs. Accepts a single UUID or a comma-separated list.
`q[status]`	String	Filter by status: `draft`, `pending`, `generating`, `success`, or `failure`. See Document Statuses.
`q[workspace_id]`	String (UUID)	Filter by workspace ID.
`q[updated_since]`	Timestamp	Only return documents updated after this point in time. Accepts a Unix timestamp (e.g. `1640995200` for 2022-01-01 00:00:00 UTC) or an ISO 8601 string.
`q[search]`	String	Search by document ID or filename. If the value is a UUID, matches by exact ID; otherwise performs a partial match on filename.

curl -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  'https://api.pdfmonkey.io/api/v1/document_cards?q[document_template_id]=2903f5b4-623b-4e10-b2e3-dc7e2e67ea39&q[status]=success&page[number]=1'

cards = Pdfmonkey::Document.list_cards(
  page: 1,
  document_template_id: '2903f5b4-623b-4e10-b2e3-dc7e2e67ea39',
  status: 'success'
)

cards.each { |card| puts card.download_url }

cards.current_page # => 1
cards.total_pages  # => 1

const params = new URLSearchParams({
  'q[document_template_id]': '2903f5b4-623b-4e10-b2e3-dc7e2e67ea39',
  'q[status]': 'success',
  'page[number]': '1',
});

const response = await fetch(
  `https://api.pdfmonkey.io/api/v1/document_cards?${params}`,
  {
    headers: {
      'Authorization': 'Bearer YOUR_SECRET_KEY',
    },
  }
);

const data = await response.json();
console.log(data.document_cards);
console.log(data.meta); // Pagination info

import requests

response = requests.get(
    'https://api.pdfmonkey.io/api/v1/document_cards',
    headers={
        'Authorization': 'Bearer YOUR_SECRET_KEY',
    },
    params={
        'q[document_template_id]': '2903f5b4-623b-4e10-b2e3-dc7e2e67ea39',
        'q[status]': 'success',
        'page[number]': 1,
    },
)

data = response.json()
print(data['document_cards'])
print(data['meta'])  # Pagination info

<?php
$query = http_build_query([
    'q' => [
        'document_template_id' => '2903f5b4-623b-4e10-b2e3-dc7e2e67ea39',
        'status' => 'success',
    ],
    'page' => ['number' => 1],
]);

$ch = curl_init("https://api.pdfmonkey.io/api/v1/document_cards?{$query}");

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

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

$data = json_decode($response, true);
print_r($data['document_cards']);
print_r($data['meta']); // Pagination info

Response

{
  "document_cards": [
    {
      "id": "a5e86d72-f5b7-43d4-a04e-8b7e08e6741c",
      "app_id": "d6b4e8f2-7a3c-4d1e-9f5b-2c8a1d3e6f90",
      "created_at": "2050-03-13T12:34:56.181+02:00",
      "document_template_id": "2903f5b4-623b-4e10-b2e3-dc7e2e67ea39",
      "document_template_identifier": "My Invoice Template",
      "download_url": "https://pdfmonkey.s3.eu-west-1.amazonaws.com/...",
      "failure_cause": null,
      "filename": "2050-03-14 Peter Parker.pdf",
      "meta": {
        "_filename": "2050-03-14 Peter Parker.pdf",
        "clientRef": "spidey-616"
      },
      "output_type": "pdf",
      "preview_url": "https://preview.pdfmonkey.io/pdf/web/viewer.html?file=...",
      "public_share_link": null,
      "status": "success",
      "updated_at": "2050-03-13T12:34:59.412+02:00"
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1
  }
}

The meta object contains pagination information:

Field	Type	Description
`current_page`	Integer	The current page number.
`next_page`	Integer or `null`	The next page number, or `null` if this is the last page.
`prev_page`	Integer or `null`	The previous page number, or `null` if this is the first page.
`total_pages`	Integer	Total number of pages available.

Update a document

PUT /api/v1/documents/{id}

Updates an existing document. You can change its payload, meta, or trigger generation by setting status to "pending".

Parameters

All parameters are nested under a document key.

Name	Type	Required	Description
`document_template_id`	String (UUID)	No	Change the template.
`payload`	Object or String	No	Replace the dynamic data.
`meta`	Object or String	No	Replace the metadata.
`status`	String	No	Set to `"pending"` to trigger generation.

curl https://api.pdfmonkey.io/api/v1/documents/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c \
  -X PUT \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "document": {
      "status": "pending",
      "payload": { "name": "Mary Jane Watson" }
    }
  }'

document = Pdfmonkey::Document.fetch('a5e86d72-f5b7-43d4-a04e-8b7e08e6741c')

document.update!(
  status: 'pending',
  payload: { name: 'Mary Jane Watson' }
)

const response = await fetch(
  'https://api.pdfmonkey.io/api/v1/documents/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c',
  {
    method: 'PUT',
    headers: {
      'Authorization': 'Bearer YOUR_SECRET_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      document: {
        status: 'pending',
        payload: { name: 'Mary Jane Watson' },
      },
    }),
  }
);

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

import requests

response = requests.put(
    'https://api.pdfmonkey.io/api/v1/documents/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c',
    headers={
        'Authorization': 'Bearer YOUR_SECRET_KEY',
    },
    json={
        'document': {
            'status': 'pending',
            'payload': {'name': 'Mary Jane Watson'},
        },
    },
)

print(response.json())

<?php
$ch = curl_init('https://api.pdfmonkey.io/api/v1/documents/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'PUT',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_SECRET_KEY',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'document' => [
            'status' => 'pending',
            'payload' => ['name' => 'Mary Jane Watson'],
        ],
    ]),
]);

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

echo $response;

Response: 200 OK with the updated document object.

Delete a document

DELETE /api/v1/documents/{id}

Permanently deletes a document and its generated file.

curl https://api.pdfmonkey.io/api/v1/documents/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c \
  -X DELETE \
  -H 'Authorization: Bearer YOUR_SECRET_KEY'

Pdfmonkey::Document.delete('a5e86d72-f5b7-43d4-a04e-8b7e08e6741c')
# => true

const response = await fetch(
  'https://api.pdfmonkey.io/api/v1/documents/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c',
  {
    method: 'DELETE',
    headers: {
      'Authorization': 'Bearer YOUR_SECRET_KEY',
    },
  }
);

console.log(response.status); // 204

import requests

response = requests.delete(
    'https://api.pdfmonkey.io/api/v1/documents/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c',
    headers={
        'Authorization': 'Bearer YOUR_SECRET_KEY',
    },
)

print(response.status_code)  # 204

<?php
$ch = curl_init('https://api.pdfmonkey.io/api/v1/documents/a5e86d72-f5b7-43d4-a04e-8b7e08e6741c');

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

curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE); // 204
curl_close($ch);

Response: 204 No Content with an empty body.

Download URLs

Download URLs are temporary signed S3 links, valid for 1 hour. To get a fresh URL after expiration, fetch the document again — no need to regenerate it. For permanent links, enable Share Links (Pro+ plans).

See Download URL for details on expiration, best practices, and troubleshooting.

Authentication — Find your API key and authenticate requests.
Templates API — List and retrieve templates to find the document_template_id you need.
Generate Documents with the API — Step-by-step guide to generating your first document.
Document Statuses and Lifecycle — Understand the draft / pending / generating / success / failure flow.
Download URL — Deep dive into download URL behavior, expiration, and best practices.
Webhooks — Receive real-time notifications when generation completes.
Custom Filename — Control the filename of generated documents via the _filename meta key.
Share Links — Permanent public URLs for generated documents (Pro+ plans).
Embedding a Preview — Embed a visual preview of your document in a web page.

Frequently asked questions

How do I generate a document with the PDFMonkey API?: Send a POST request to /api/v1/documents with your template ID and dynamic data. Set status to "pending" to queue generation immediately. Then poll the document status or use webhooks to know when the file is ready to download.
What is the difference between Document and DocumentCard in PDFMonkey?: A Document is the full object including payload, generation_logs, and checksum. A DocumentCard is a lighter version without those fields but with document_template_identifier added. Use DocumentCards when you don't need the payload.
Does PDFMonkey support synchronous document generation?: Yes. POST to /api/v1/documents/sync to create a document and wait for the result in a single request. The endpoint has a 6-minute timeout and returns a DocumentCard.
How long is a PDFMonkey download URL valid?: Download URLs are temporary signed S3 URLs valid for 1 hour. After expiration, fetch the document again to get a fresh URL -- no need to regenerate.

Documents API: Create, List, and Manage Generated Documents

Quick start

Authentication

Create a document

Parameters

Request

Response

Validation errors

Synchronous generation

When to use sync vs async

Request

Response

The Document object

Attributes

The DocumentCard object

Attributes

Comparison: Document vs DocumentCard

Get a document

Get a DocumentCard (recommended)

Get a full Document

List documents

Query parameters

Response

Update a document

Parameters

Delete a document

Download URLs

Related pages

Frequently asked questions