### Bundle Install Command

Source: https://pdfmonkey.io/docs/integrations/ruby-sdk

Execute the bundle command after adding the gem to your Gemfile to install it.

```bash
$ bundle
```

--------------------------------

### Dynamic Filename Examples

Source: https://pdfmonkey.io/docs/integrations/n8n

Examples of constructing dynamic filenames using static text combined with n8n expressions. Ensure filenames adhere to OS restrictions.

```plaintext
Invoice-{{ $json.invoiceNumber }}.pdf
Report-{{ $now.format('YYYY-MM-DD') }}.pdf
{{ $json.customerName }}-Contract.pdf
```

--------------------------------

### Install PDFMonkey CLI

Source: https://pdfmonkey.io/docs/code-templates/cli

Install the PDFMonkey CLI globally using npm. This command makes the `pdfmonkey` executable available in your terminal.

```bash
npm install -g @pdfmonkey/cli
```

--------------------------------

### Install PDFMonkey Gem Manually

Source: https://pdfmonkey.io/docs/integrations/ruby-sdk

Alternatively, install the PDFMonkey gem directly using the gem install command.

```bash
$ gem install pdfmonkey
```

--------------------------------

### Resource metadata structure

Source: https://pdfmonkey.io/docs/code-templates/cli

Example of the .pdfmonkey.json metadata file used to identify resources.

```json
{
  "type": "template",
  "id": "123e4567-e89b-12d3-a456-426614174000"
}
```

--------------------------------

### Get PDFMonkey CLI Help

Source: https://pdfmonkey.io/docs/code-templates/cli

Run this command to view a list of all available commands and general help information for the PDFMonkey CLI.

```bash
pdfmonkey help
```

--------------------------------

### Create a registration form

Source: https://pdfmonkey.io/docs/code-templates/pdf-forms

A comprehensive registration form example using dropdowns, date pickers, and number fields with specific constraints.

```html
<h1>Registration Form</h1>

<h2>Personal Information</h2>
<p>Title: [% data_form_field_dropdown_civility_w100_h30_options[Mr,Mrs,Ms] %]</p>
<p>Last name: [% data_form_field_text_lastname_w250_h30_required %]</p>
<p>First name: [% data_form_field_text_firstname_w250_h30_required %]</p>
<p>Birth date: [% data_form_field_date_birthdate_w150_h30_format_dd_mm_yyyy %]</p>
<p>Age: [% data_form_field_number_age_w80_h30_min18_max120 %]</p>

<h2>Contact</h2>
<p>Email: [% data_form_field_text_email_w350_h30_required_email %]</p>
<p>Phone: [% data_form_field_text_phone_w200_h30_phone %]</p>

<h2>Address</h2>
<p>Street: [% data_form_field_text_address_w450_h30_required %]</p>
<p>Postal code: [% data_form_field_text_zipcode_w120_h30_max5_comb %]</p>
<p>City: [% data_form_field_text_city_w250_h30_required %]</p>
<p>Country: [% data_form_field_dropdown_country_w250_h30_options[France,Belgium,Switzerland,Canada] %]</p>

<h2>Terms</h2>
<p>☐ I accept the terms [% data_form_field_checkbox_accept_terms_w20_h20_required %]</p>
<p>☐ Subscribe to newsletter [% data_form_field_checkbox_newsletter_w20_h20 %]</p>
```

--------------------------------

### Document creation response

Source: https://pdfmonkey.io/docs/generating-documents/api-pdf-generation

Example of the JSON response received after a successful POST request.

```json
{
  "document": {
    "id": "a5e86d72-f5b7-43d4-a04e-8b7e08e6741c",
    "status": "pending",
    "download_url": null,
    ...
  }
}
```

--------------------------------

### Checkbox Field Examples

Source: https://pdfmonkey.io/docs/code-templates/pdf-forms

Use these markers to create checkboxes. They can be marked as required. The example shows how to embed them within text.

```html
[% data_form_field_checkbox_w20_h20 %]
```

```html
[% data_form_field_checkbox_accept_terms_w20_h20_required %]
```

```html
<p>☐ I accept the terms [% data_form_field_checkbox_accept_w20_h20 %]</p>
<p>☐ Subscribe to newsletter [% data_form_field_checkbox_newsletter_w20_h20 %]</p>
```

--------------------------------

### Basic Liquid Syntax Example

Source: https://pdfmonkey.io/docs/code-templates/the-liquid-syntax

Demonstrates common Liquid syntax including output tags, logic tags, and filters for dynamic content generation in PDF templates.

```liquid
<h1>Invoice #{{invoiceNumber}}</h1>
<p>Date: {{"now" | date: "%B %d, %Y"}}</p>
<p>Client: {{client.fullName}}</p>

<table>
  <tr>
    <th>Product</th>
    <th>Qty</th>
    <th>Price</th>
  </tr>

  {% for item in lineItems %}
    <tr>
      <td>{{item.product}}</td>
      <td>{{item.quantity}}</td>
      <td>{{item.price | times: item.quantity | with_delimiter, precision: 2}}</td>
    </tr>
  {% endfor %}
</table>

{% if client.isNewClient %}
  <p>Welcome aboard! Enjoy 10% off your next order.</p>
{% endif %}
```

--------------------------------

### Create a contact form

Source: https://pdfmonkey.io/docs/code-templates/pdf-forms

A complete example demonstrating various field types including text, textarea, and checkbox with validation constraints.

```html
<h1>Contact Form</h1>

<p>Last name: [% data_form_field_text_lastname_w300_h30_required %]</p>
<p>First name: [% data_form_field_text_firstname_w300_h30_required %]</p>
<p>Email: [% data_form_field_text_email_w350_h30_required_email %]</p>
<p>Phone: [% data_form_field_text_phone_w200_h30_phone %]</p>

<p>Message:</p>
<p>[% data_form_field_textarea_message_w500_h120_required_max1000 %]</p>

<p>☐ I agree to be contacted [% data_form_field_checkbox_accept_w20_h20 %]</p>
```

--------------------------------

### Number Field Examples

Source: https://pdfmonkey.io/docs/code-templates/pdf-forms

Create number input fields with optional minimum and maximum value constraints.

```html
[% data_form_field_number_w100_h30 %]
```

```html
[% data_form_field_number_age_w80_h30_min18_max120 %]
```

```html
[% data_form_field_number_quantity_w60_h30_min1_max99 %]
```

--------------------------------

### Dropdown (Select) Field Examples

Source: https://pdfmonkey.io/docs/code-templates/pdf-forms

Create dropdown menus with predefined options using this marker. All options must be specified within the marker.

```html
[% data_form_field_dropdown_w250_h30_options[Option1,Option2,Option3] %]
```

```html
[% data_form_field_dropdown_country_w300_h30_options[France,Belgium,Switzerland,Canada] %]
```

--------------------------------

### Initialize a PDFMonkey Template

Source: https://pdfmonkey.io/docs/code-templates/cli

Start editing a PDFMonkey template by initializing it locally. You can specify the template ID and destination folder.

```bash
pdfmonkey template init
```

```bash
pdfmonkey tpl init <template-id>
```

```bash
pdfmonkey template init <template-id> <destination-folder>
```

--------------------------------

### Preview Template with Live Reload

Source: https://pdfmonkey.io/docs/code-templates/cli

Start the template watch command and automatically open the preview in your browser using the `-o` or `--open-browser` option.

```bash
pdfmonkey template watch -o
```

--------------------------------

### List document cards via API

Source: https://pdfmonkey.io/docs/api/documents

Examples of how to retrieve a paginated list of document cards using various programming languages and tools.

```bash
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'
```

```ruby
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
```

```javascript
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
```

```python
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
<?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
```

--------------------------------

### Install PDFMonkey Ruby Gem

Source: https://pdfmonkey.io/docs/integrations/ruby-sdk

Add the PDFMonkey gem to your application's Gemfile to begin using the SDK.

```ruby
gem 'pdfmonkey'
```

--------------------------------

### Watch and Sync Template Changes

Source: https://pdfmonkey.io/docs/code-templates/cli

Start watching a template folder for changes and automatically sync them to PDFMonkey. This command uses the `.pdfmonkey.json` metadata file.

```bash
pdfmonkey template watch
```

```bash
pdfmonkey template watch <path>
```

```bash
pdfmonkey template watch [path] -t <template-id>
```

--------------------------------

### Generate Document Synchronously

Source: https://pdfmonkey.io/docs/api/documents

Examples of how to trigger a synchronous document generation request across various programming languages and tools.

```bash
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"
      }
    }
  }'
```

```ruby
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://…'
```

```javascript
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);
```

```python
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
<?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'];
```

--------------------------------

### Generate a Document via API

Source: https://pdfmonkey.io/docs/api/documents

Examples of how to trigger document generation by sending a POST request to the PDFMonkey API endpoint.

```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": "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"
      }
    }
  }'
```

```ruby
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'
```

```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: '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);
```

```python
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
<?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;
```

--------------------------------

### Fetch Document Details via API

Source: https://pdfmonkey.io/docs/troubleshooting/download-url-gives-403

Send a GET request to the documents endpoint to retrieve a fresh download URL. Ensure you include your API key in the Authorization header.

```bash
curl https://api.pdfmonkey.io/api/v1/documents/YOUR_DOCUMENT_ID \
  -H "Authorization: Bearer YOUR_SECRET_API_KEY"
```

--------------------------------

### Date Field Examples (with Format)

Source: https://pdfmonkey.io/docs/code-templates/pdf-forms

Use these markers for date inputs. You can specify the display format (e.g., DD/MM/YYYY, MM/DD/YYYY, YYYY-MM-DD) and mark the field as required.

```html
[% data_form_field_date_w150_h30_format_dd_mm_yyyy %]
```

```html
[% data_form_field_date_birthdate_w150_h30_format_dd_mm_yyyy_required %]
```

--------------------------------

### Get Full Document Template

Source: https://pdfmonkey.io/docs/api/templates

Retrieve a complete document template, including its body, styles, and test data, by its ID. Requires an API key for authorization.

```bash
curl -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  https://api.pdfmonkey.io/api/v1/document_templates/8ac0d8f7-dbd3-46dd-b2d3-af036a2776d9
```

```ruby
template = Pdfmonkey::Template.fetch('8ac0d8f7-dbd3-46dd-b2d3-af036a2776d9')

puts template.identifier
puts template.body
puts template.settings
```

```javascript
const response = await fetch(
  'https://api.pdfmonkey.io/api/v1/document_templates/8ac0d8f7-dbd3-46dd-b2d3-af036a2776d9',
  {
    headers: {
      'Authorization': 'Bearer YOUR_SECRET_KEY',
    },
  }
);

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

```python
import requests

response = requests.get(
    'https://api.pdfmonkey.io/api/v1/document_templates/8ac0d8f7-dbd3-46dd-b2d3-af036a2776d9',
    headers={
        'Authorization': 'Bearer YOUR_SECRET_KEY',
    },
)

data = response.json()
print(data['document_template'])
```

```php
<?php
$ch = curl_init('https://api.pdfmonkey.io/api/v1/document_templates/8ac0d8f7-dbd3-46dd-b2d3-af036a2776d9');

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_template']);
```

--------------------------------

### Test API Authentication with curl

Source: https://pdfmonkey.io/docs/api/authentication

Use curl to make a GET request to the current_user endpoint to verify your API key is working correctly. A successful response will return your account information.

```bash
curl https://api.pdfmonkey.io/api/v1/current_user \
  -H "Authorization: Bearer YOUR_SECRET_KEY"
```

--------------------------------

### Include a Partial within a Template Loop

Source: https://pdfmonkey.io/docs/code-templates/reusing-code

This example demonstrates including a defined partial named 'line-item' within a loop. Each iteration passes a 'lineItem' as the 'product' variable to the partial.

```liquid
{% for lineItem in lineItems %}
  {% include 'line-item', product: lineItem %}
{% endfor %}
```

--------------------------------

### Load Luxon Library in HTML

Source: https://pdfmonkey.io/docs/code-templates/custom-javascript

Demonstrates loading the Luxon library via CDN and performing date manipulation within a template.

```html
<script src="https://cdn.jsdelivr.net/npm/luxon@2.3.1/build/global/luxon.min.js"></script>
<script>
  let { DateTime } = luxon;
  let date = DateTime.fromISO("2050-01-01T12:34:56");
  date.plus({ days: 3 }).setZone('Pacific/Honolulu').toLocaleString(DateTime.DATETIME_HUGE);
  //=> "Tuesday, 4 January 2050, 01:34 Hawaii-Aleutian Standard Time"
</script>
```

--------------------------------

### Invalid JSON key examples

Source: https://pdfmonkey.io/docs/builder-templates/test-data

Examples of JSON keys that cause conflicts or syntax errors because they are not valid JavaScript identifiers.

```json5
{
  "some.variable": "Some value",       // Dot conflicts with property access
  "some variable": "Some value",       // Spaces break expressions
  "(someVariable)": "Some value",      // Parentheses are operators in JS
  "'someVariable'": "Some value",      // Quotes aren't valid in identifiers
  "{{someVariable}}": "Some value",    // Braces are syntax characters
  "some-variable": "Some value",      // Hyphen is the minus operator in JS
  "2": "Some value",                   // Bare numbers aren't identifiers
  "2words": "Some value"               // Starts with a digit
}
```

--------------------------------

### Custom JSON Example for Zapier

Source: https://pdfmonkey.io/docs/integrations/zapier

This is an example of custom JSON used in Zapier. Ensure that values containing special characters like double quotes are properly escaped to avoid errors.

```json5
{
  "user": {
    "name": "(Dynamic Field From Zapier)"
  }
}
```

--------------------------------

### Set Preview Ports via Environment Variables

Source: https://pdfmonkey.io/docs/code-templates/cli

Alternatively, customize the preview and live-reload ports by setting the `PORT` and `LIVE_RELOAD_PORT` environment variables.

```bash
PORT=2083 LIVE_RELOAD_PORT=2084 pdfmonkey template watch
```

--------------------------------

### Create and Poll Document Generation

Source: https://pdfmonkey.io/docs/api/documents

Demonstrates the asynchronous workflow of queuing a document for generation and polling for its status.

```bash
# 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
```

--------------------------------

### Dotted Guide Line Technique for Forms

Source: https://pdfmonkey.io/docs/code-templates/pdf-forms

This technique combines a borderless form field with manually drawn dotted lines to guide user input, creating a cleaner aesthetic. The marker text is set to white to be invisible.

```html
<p style="color: white;">[% data_form_field_text_email_w350_h30_noborder_email %]</p>
<p style="border-bottom: 1px dotted #999; width: 350px;"></p>
```

--------------------------------

### GET /api/v1/engines

Source: https://pdfmonkey.io/docs/api/templates

Retrieves a list of available PDF engines supported by the platform.

```APIDOC
## GET /api/v1/engines

### Description
Retrieves the list of available PDF engines.

### Method
GET

### Endpoint
/api/v1/engines

### Response
#### Success Response (200)
- **pdf_engines** (Array) - List of available engines.
- **meta** (Object) - Pagination metadata.

#### Response Example
{
  "pdf_engines": [
    { "id": "5c709522-90db-4aea-b49f-15aeaa7180c7", "name": "v4", "deprecated_on": null },
    { "id": "61749ef7-6aca-4edb-84ca-685adb638c34", "name": "v3", "deprecated_on": null },
    { "id": "1f8da2ab-29c4-455c-a5fb-8771e44148c3", "name": "v2", "deprecated_on": null }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1
  }
}
```

--------------------------------

### Open Template in Editor

Source: https://pdfmonkey.io/docs/code-templates/cli

Initialize a template and automatically open the created folder in your default code editor using the `-e` or `--edit` flag.

```bash
pdfmonkey template init <template-id> -e
```

--------------------------------

### Create a template

Source: https://pdfmonkey.io/docs/integrations/ruby-sdk

Create a new template using the `create` method. Attributes like `body`, `scss_style`, `settings`, `sample_data`, and `pdf_engine_id` are automatically written to their draft counterparts.

```ruby
template = Pdfmonkey::Template.create(
  identifier: 'my-invoice',
  body: '<h1>Invoice</h1>'
)
template.body_draft # => '<h1>Invoice</h1>'
```

--------------------------------

### Handle validation errors

Source: https://pdfmonkey.io/docs/api/templates

Example of the JSON response returned by the API when a request fails validation.

```json
{
  "errors": {
    "identifier": ["can't be blank"]
  }
}
```

--------------------------------

### Password Field Example

Source: https://pdfmonkey.io/docs/code-templates/pdf-forms

This marker creates a password input field, which masks the entered characters.

```html
[% data_form_field_text_password_w250_h30_password %]
```

--------------------------------

### Chart.js Data Payload

Source: https://pdfmonkey.io/docs/code-templates/custom-javascript

Example JSON structure for providing chart data to a PDFMonkey template.

```json
{
  "chart": {
    "labels": ["Jan", "Feb", "Mar", "Apr", "May"],
    "values": [120, 190, 150, 210, 175]
  }
}
```

--------------------------------

### Fetch a template

Source: https://pdfmonkey.io/docs/integrations/ruby-sdk

Fetch a full template, including its body and settings, using the `fetch` or `fetch_full` method. Use `list_cards` if only metadata is needed, as full templates can be large.

```ruby
template = Pdfmonkey::Template.fetch('b13ebd75-d290-409b-9cac-8f597ae3e785')
template.identifier # => 'my-invoice'
template.body       # => '<h1>Invoice</h1>…'  (published version)
template.body_draft # => '<h1>Invoice v2</h1>…'  (draft version)
```

--------------------------------

### Fetch a Snippet

Source: https://pdfmonkey.io/docs/integrations/ruby-sdk

Retrieves a specific snippet by its ID. Use this to get the code or details of a snippet.

```ruby
# Fetch a snippet
snippet = Pdfmonkey::Snippet.fetch('snippet-id')
```

--------------------------------

### Initialize a PDFMonkey snippet

Source: https://pdfmonkey.io/docs/code-templates/cli

Commands to initialize a snippet for editing, with options for specifying IDs and destination folders.

```bash
pdfmonkey snippet init
```

```bash
pdfmonkey snippet init <snippet-id>
```

```bash
pdfmonkey snippet init <snippet-id> <destination-folder>
```

```bash
pdfmonkey snippet init <snippet-id> -e
```

--------------------------------

### Define Valid Variable Keys

Source: https://pdfmonkey.io/docs/builder-templates/test-data

Examples of valid JSON keys that can be referenced as variables within the builder.

```json5
{
  "someVariable": "Some value",
  "some_variable": "Some value",
  "SomeVariable": "Some value",
  "somevariable": "Some value",
  "$someVariable": "Some value",
  "some": { "variable": "Some value" }
}
```

--------------------------------

### Define Template Test Data

Source: https://pdfmonkey.io/docs/builder-templates/test-data

Example of a standard JSON object used to populate template variables.

```json
{
  "name": "Jane Smith",
  "company": "Acme Corp",
  "date": "2025-03-15",
  "items": [
    { "description": "Widget A", "quantity": 2, "price": 19.99 },
    { "description": "Widget B", "quantity": 1, "price": 49.99 }
  ],
  "logo_url": "https://example.com/logo.png"
}
```

--------------------------------

### Workflow: Generate, Store, and Clean Up

Source: https://pdfmonkey.io/docs/integrations/n8n

Automate the generation, storage in Google Drive, database logging, and subsequent deletion of a document.

```text
1. Manual Trigger
2. PDFMonkey - Generate Document (Download: enabled)
3. Google Drive - Upload File
   - File: {{ $binary.data }}
   - Folder: /Invoices/
4. Postgres - Insert
   - Table: documents
   - Data: {
       drive_url: {{ $node["Google Drive"].json.webViewLink }},
       pdfmonkey_id: {{ $node["PDFMonkey"].json.id }}
     }
5. PDFMonkey - Delete Document
   - Document ID: {{ $node["PDFMonkey"].json.id }}
```

--------------------------------

### GET /api/v1/document_cards

Source: https://pdfmonkey.io/docs/api/documents

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

```APIDOC
## GET /api/v1/document_cards

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

### Method
GET

### Endpoint
/api/v1/document_cards

### Parameters
#### Query Parameters
- **page[number]** (Integer) - Optional - Page number (default: 1).
- **q[document_template_id]** (String/Array) - Optional - Filter by one or more template IDs.
- **q[status]** (String) - Optional - Filter by status: draft, pending, generating, success, or failure.
- **q[workspace_id]** (String) - Optional - Filter by workspace ID.
- **q[updated_since]** (Timestamp) - Optional - Only return documents updated after this point in time.
- **q[search]** (String) - Optional - Search by document ID or filename.

### Response
#### Success Response (200)
- **document_cards** (Array) - List of document card objects.
- **meta** (Object) - Pagination information.

#### Response Example
{
  "document_cards": [
    {
      "id": "a5e86d72-f5b7-43d4-a04e-8b7e08e6741c",
      "status": "success",
      "filename": "2050-03-14 Peter Parker.pdf"
    }
  ],
  "meta": {
    "current_page": 1,
    "total_pages": 1
  }
}
```

--------------------------------

### Get a DocumentCard

Source: https://pdfmonkey.io/docs/api/documents

Retrieves a DocumentCard object, which is recommended for checking generation status and obtaining download URLs.

```APIDOC
## GET /api/v1/document_cards/{id}

### Description
Returns a [DocumentCard](#the-documentcard-object) for the given document. This is the recommended way to check generation status and retrieve the download URL.

### Method
GET

### Endpoint
/api/v1/document_cards/{id}

### Parameters
#### Path Parameters
- **id** (String (UUID)) - Required - Unique identifier for the document.

### Response
#### Success Response (200)
- **document_card** (Object) - Contains the DocumentCard object with details like status and download URL.

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

--------------------------------

### Retrieve document information

Source: https://pdfmonkey.io/docs/integrations/n8n

Use the Get Document operation to fetch details about a document using its ID.

```text
Document ID: {{ $json.documentId }}
```

--------------------------------

### Successful document response

Source: https://pdfmonkey.io/docs/generating-documents/download-url

Example of the API response structure when a document is successfully generated, including the download_url field.

```json
{
  "document": {
    "id": "a5e86d72-f5b7-43d4-a04e-8b7e08e6741c",
    "status": "success",
    "download_url": "https://pdfmonkey-production.s3.eu-west-1.amazonaws.com/...",
    "preview_url": "https://preview.pdfmonkey.io/...",
    "public_share_link": null
  }
}
```

--------------------------------

### Document Generation with Metadata

Source: https://pdfmonkey.io/docs/integrations/ruby-sdk

Demonstrates how to generate documents (PDFs or images) and attach metadata, such as filenames and client IDs.

```APIDOC
## Document Generation with Metadata

### Description
Generate documents (PDFs or images) and attach metadata using the `meta:` keyword argument.

### Method
`POST` (implied by `generate!` and `generate` methods)

### Endpoint
`/documents` (implied)

### Parameters
#### Request Body
- **document_template_id** (string) - Required - The ID of the document template.
- **payload** (object) - Required - The data to populate the document.
- **meta** (object) - Optional - Metadata to attach to the document.
  - **_filename** (string) - Optional - The desired filename for the generated document.
  - **client_id** (string) - Optional - A custom client identifier.
  - **_type** (string) - Optional - For image generation: 'png', 'jpg', or 'webp' (default).
  - **_width** (integer) - Optional - For image generation: desired width in pixels.
  - **_height** (integer) - Optional - For image generation: desired height in pixels.
  - **_quality** (integer) - Optional - For image generation (webp only): quality from 0 to 100 (default 100).

### Request Example
```ruby
meta = {
  _filename: 'john-doe-contract.pdf',
  client_id: '123xxx123'
}

document = Pdfmonkey::Document.generate!(
  document_template_id: template_id,
  payload: payload,
  meta: meta
)
```

### Response
#### Success Response (200)
- **meta** (string) - The attached metadata as a JSON string.

#### Response Example
```ruby
# Assuming the above request was made
document.meta
# => '{"_filename":"john-doe-contract.pdf","client_id":"123xxx123"}'
```
```

--------------------------------

### Create a document via API

Source: https://pdfmonkey.io/docs/generating-documents/api-pdf-generation

Send a POST request to the documents endpoint to initiate PDF generation. Requires a valid API key and template ID.

```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
# 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://…'
```

```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
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
$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));
```

--------------------------------

### Define E-commerce Order Data

Source: https://pdfmonkey.io/docs/code-templates/defining-dynamic-data

Example of a JSON structure representing an order, including nested objects and arrays.

```json
{
  "orderId": 1234,
  "orderStatus": "pending",
  "invoiceId": null,
  "client": {
    "civility": "Mr",
    "fullName": "Peter Parker",
    "isNewClient": true
  },
  "lineItems": [
    { "product": "Super strong silk",     "quantity": 100, "price": 123.45 },
    { "product": "Electronic components", "quantity": 12,  "price": 12.34 }
  ]
}
```

--------------------------------

### GET /api/v1/document_cards/:id

Source: https://pdfmonkey.io/docs/generating-documents/api-pdf-generation

Retrieves the status and details of a specific document, including the download URL once generation is complete.

```APIDOC
## GET /api/v1/document_cards/:id

### Description
Poll this endpoint to check the generation status of a document. Once the status is 'success', the download_url field will be populated.

### Method
GET

### Endpoint
/api/v1/document_cards/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the document

### Response
#### Success Response (200)
- **document** (object) - The document object containing current status and download_url.
```

--------------------------------

### Create a Template Folder

Source: https://pdfmonkey.io/docs/integrations/ruby-sdk

Creates a new template folder with a specified identifier. This helps organize templates.

```ruby
# Create a folder
folder = Pdfmonkey::TemplateFolder.create(identifier: 'invoices')
```

--------------------------------

### Watch multiple resources

Source: https://pdfmonkey.io/docs/code-templates/cli

Commands to watch multiple templates and snippets simultaneously.

```bash
pdfmonkey watch
```

```bash
pdfmonkey watch path/to/template path/to/snippet
```

```bash
pdfmonkey watch -D -o -p 2083 -l 2084
```

--------------------------------

### Phone Field Example

Source: https://pdfmonkey.io/docs/code-templates/pdf-forms

This marker creates a phone number input field, which can be used for basic phone number entry.

```html
[% data_form_field_text_phone_w200_h30_phone %]
```