PDFDispatch Docs

URL to PDF

Give a URL; a browser opens it, runs its scripts and prints it. For pages that are already online, such as a report in your web app.

POST https://api.pdfdispatch.com/v1/convert/url

Form fields

FieldTypeDefaultWhat it does
url requiredstring–The page to print, http:// or https://, on the public internet. file:// is refused.
header.html, footer.htmlfile–Repeated at the top and bottom of every page. See Header and footer.

Plus the usual page options:

FieldTypeDefaultWhat it does
paperWidth, paperHeightsize8.5 × 11 (US Letter)The paper size. A number is inches; add a unit for others: 210mm, 29.7cm, 595pt, 794px, 50pc. A4 is 210mm × 297mm.
marginTop, marginBottom, marginLeft, marginRightsize0.39 (1 cm)The page margins, in the same units. A header or footer is drawn inside the top or bottom margin.
landscapebooleanfalseTurn the paper sideways.
printBackgroundbooleanfalsePrint background colours and images. Without it, most backgrounds are left out, as a browser does when it prints.
preferCssPageSizebooleanfalseUse the size from the page’s CSS @page rule instead of paperWidth and paperHeight.
waitDelayduration–Wait this long after the page has loaded before printing, for example 500ms or 2s. See Waiting for better ways.
emulatedMediaTypestringprintprint or screen: which CSS media rules apply.

All other options, including cookies and headers for pages behind a login, are on Rendering options. Headers of the request (Output-Filename, Webhook-*) are as for HTML.

Example

curl --fail-with-body \
  --header "Authorization: Bearer $PDD_KEY" \
  --form url=https://example.com/reports/2026-10 \
  --form waitForSelector='#chart[data-ready]' \
  --form printBackground=true \
  --output report.pdf \
  https://api.pdfdispatch.com/v1/convert/url

The same in Python:

import os
import requests

res = requests.post(
    "https://api.pdfdispatch.com/v1/convert/url",
    headers={"Authorization": f"Bearer {os.environ['PDD_KEY']}"},
    # No file to upload, but the body must still be multipart: (None, value) makes a plain field.
    files={"url": (None, "https://example.com/reports/2026-10"), "printBackground": (None, "true")},
    timeout=70,
)
res.raise_for_status()
open("report.pdf", "wb").write(res.content)

Pages behind a login

The browser starts empty for every request: no cookies, no session. To print a page your users see after logging in, give the browser what it needs to get in, for this one request:

  • a short-lived session cookie in cookies: [{"name": "session", "value": "abc123", "domain": "app.example.com", "secure": true, "httpOnly": true}]
  • or a token header in extraHttpHeaders, limited to your site with a scope: {"Authorization": "Bearer short-lived-token;scope=https://app\\.example\\.com/.*"}

Make such cookies and tokens expire within minutes and allow only reading. A signed, single-use link to a print view of the page is often simplest of all.

Things to know

  • The page must be on the public internet; private and local addresses are refused with 403 (details).
  • By default the conversion fails with 409 when the page answers with a 4xx or 5xx status, so you do not get a PDF of an error page. Change this with failOnHttpStatusCodes.
  • Pages that load their content with JavaScript may need a wait: waitForSelector, waitForExpression or waitDelay (Waiting).
  • Cookie banners and chat widgets print too. Hide them in a print stylesheet, or print a dedicated print view.