Files and results

How files go in, what comes out, and what the API may fetch from the internet on your behalf.

Sending files

Requests are multipart/form-data, also when there is no file to upload (a URL conversion): a URL-encoded or JSON body gets 415. Each file is a part with a file name; each option is a text part. Every HTTP library can build such a body (see the examples), and with curl it is --form files=@path for a file and --form name=value for an option.

The file name of each part is what counts: index.html for HTML, the extension (.pdf, .docx, .md, …) for the others. The name of the part itself does not matter, except for these:

Field	Type	Default	What it does
`files`	file(s)	–	The documents to work on. Any part name works for these; we write `files` in every example.
`embeds`	file(s)	–	Files to attach inside the PDF (Attachments), not to convert.
`watermark`	file(s)	–	The images or PDFs for `watermarkSource=image` or `pdf`, in order.
`stamp`	file(s)	–	The images or PDFs for `stampSource=image` or `pdf`, in order.
`facturxXml`	file	–	The invoice XML for Factur-X.
`downloadFrom`	JSON array	–	Files for us to fetch from URLs instead of uploading them. See below.

Things to know:

Names are flattened. Folders in a file name are dropped (img/logo.png arrives as logo.png), so refer to your assets by file name only.
Two files with the same name are both kept: the second becomes name (2).ext.
Order. Where order matters (merging), files are sorted by name, with numbers in their natural order: 2-intro.pdf comes before 10-appendix.pdf. Name your files to get the order you want.
Booleans are the text true or false. JSON options (metadata, cookies, …) are JSON text in an ordinary field.

Files from URLs: downloadFrom

Instead of uploading a file, you can have the API fetch it. Send a field downloadFrom with a JSON array; each entry is one file:

Field	Type	Default	What it does
`url` required	string	–	Where to fetch the file. It must answer `200` with a `Content-Disposition` header that has a `filename`; that name is the file’s name in the request.
`extraHttpHeaders`	JSON object	–	Headers for that one fetch, for example a token for your storage.
`field`	string	–	`embedded`, `watermark` or `stamp` to use the file as an attachment, watermark or stamp. Without it, it is a document to work on.

curl --header "Authorization: Bearer $PDD_KEY" \
  --form 'downloadFrom=[{"url": "https://files.example.com/contract.docx", "extraHttpHeaders": {"Authorization": "Bearer storage-token"}}]' \
  --output contract.pdf \
  https://api.pdfdispatch.com/v1/convert/office

Fetched files count towards your plan’s size limit like uploaded ones, and a fetch that fails (not 200, no file name) fails the request with 400. Uploads and downloadFrom can be mixed in one request.

What comes back

The request makes	You get
one file	that file: `application/pdf`, or `image/png`, `image/jpeg`, `image/webp` for screenshots
several files	a ZIP (`application/zip`) with one entry per file
a read (metadata, bookmarks)	JSON

The Content-Disposition header names the file. Without an Output-Filename header the name is random; with Output-Filename: report it is report.pdf (or report.zip). The names of the files inside a ZIP come from your input files.

What the API may fetch

The browser behind the HTML, URL and Markdown routes loads pages and their images, styles and scripts; the API fetches downloadFrom files and calls your webhooks. All of that goes out to the public internet only:

localhost, private networks (10.x, 172.16-31.x, 192.168.x and their IPv6 counterparts), link-local and cloud metadata addresses are refused, also when a public name points to them or a redirect leads there.
A refused url, downloadFrom entry or webhook URL fails the request with 403.
A refused image, style or script inside a page is simply left out, and the PDF is still made. (Add failOnResourceLoadingFailed=true if you would rather have an error.)
file:// URLs are refused on the URL routes. HTML and Markdown routes may load only the files of the same request.

To print something that lives on a private network, send it as files instead, or make it reachable over HTTPS for the time of the request (with a token in extraHttpHeaders or cookies).