Set a Custom Filename for Generated Documents

Last updated March 23, 2026

By default, PDFMonkey names generated files using an internal identifier. You can override this by passing a _filename key in the document’s metadata – this works for both PDFs and images.

Setting the filename via the API

Include the _filename key inside the meta object when you create or update a document:

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" },
      "meta": {
        "_filename": "invoice-2050-03.pdf"
      }
    }
  }'

The meta field accepts a JSON object. You can include other metadata keys alongside _filename – see API Documents reference for full details.

Setting the filename from the Dashboard

  1. Open a document in the Document Editor.
  2. Switch to the Meta data tab.
  3. Enter the _filename key and your desired name:
{
  "_filename": "invoice-2050-03.pdf"
}
  1. Click Save, then Generate.

For a full walkthrough, see Generate Documents from the Dashboard.

File extension handling

PDFMonkey manages the file extension automatically based on the output format (PDF, PNG, WebP, or JPG):

  • If you include the matching extension (e.g. invoice.pdf for a PDF template), PDFMonkey strips it and re-appends it to keep the filename clean.
  • If you omit the extension, PDFMonkey appends the correct one for you.
  • If you include a mismatched extension (e.g. .png on a PDF document), it is treated as part of the name and the correct extension is still appended.
You don’t need to worry about the extension. Just provide the name you want and let PDFMonkey handle the rest.

Filename sanitization

PDFMonkey sanitizes the _filename value to ensure it is safe for all file systems:

RuleExample
Accented characters are transliterated to ASCIIcafe-resume becomes cafe-resume
Characters other than letters, digits, dashes, underscores, and spaces are replaced with a dashreport@2050/03 becomes report-2050-03
Consecutive dashes are collapsedreport---final becomes report-final
Leading and trailing dashes are removed-my-file- becomes my-file
Whitespace is trimmed from both ends" invoice " becomes "invoice"

For example, an input of "Facture n 2050/03" for a PDF template produces the filename Facture n-2050-03.pdf.

Works with images too

The _filename key works the same way for image output formats. The extension is adjusted to match the image type (.webp, .png, or .jpg):

{
  "meta": {
    "_filename": "social-card-march",
    "_type": "png"
  }
}

This produces a file named social-card-march.png.

Frequently asked questions

What happens if I don’t set a custom filename?

PDFMonkey uses an internal default name. If you need predictable filenames for archival or downstream systems, always set _filename.

Can I use dynamic data in the filename?

Not directly inside the _filename value. However, in most integration platforms (Zapier, Make, n8n) you can use dynamic fields or expressions to build the filename string before passing it to PDFMonkey.

Is there a maximum filename length?

There is no explicit limit enforced by PDFMonkey, but keep filenames reasonable (under 200 characters) to avoid issues with file systems and browsers.

Frequently asked questions

How do I set a custom filename for a PDFMonkey document?
Pass a "_filename" key in the document's meta field. Via the API, include it in the meta object when creating or updating a document: "meta": { "_filename": "invoice-2050.pdf" }. In the Dashboard, enter it in the Meta data tab of the Document Editor.
Does PDFMonkey add the file extension automatically?
Yes. If you include the correct extension (.pdf, .png, .webp, .jpg), PDFMonkey strips it and re-adds it to keep the filename clean. If you omit the extension, PDFMonkey appends it automatically based on the output format.
What characters are allowed in the custom filename?
PDFMonkey sanitizes the filename: accented characters are transliterated to ASCII, any character that is not a letter, digit, dash, underscore, or space is replaced with a dash, and consecutive or leading/trailing dashes are removed.
Navigation