How to Add Custom Headers and Footers to PDFs with PDFCrowd
Add branded headers, footers, and page numbers to PDFCrowd PDFs. Learn the API parameters, layout sizing, page exclusions, and configuration precedence.
To add custom headers and footers with PDFCrowd’s HTML-to-PDF API, pass inline templates using header_html and footer_html, or provide template URLs with header_url and footer_url. Put an element with class pdfcrowd-page-number or pdfcrowd-page-count in a template to insert the current printed page number or total page count. Set header_height and footer_height to reserve enough room so the running content does not overlap the document body.
This guide uses PDFCrowd’s HTTP API parameter names. For the current API reference and language-specific client methods, see the PDFCrowd HTTP API reference and official method index. The examples below show the request shape; replace the placeholder API credentials with the authentication method required by your PDFCrowd account and current API reference.
1. Choose inline HTML or a hosted template
Use inline HTML when the header or footer belongs to one conversion request. Use header_url and footer_url when you already serve reusable template HTML at an HTTP or HTTPS URL. The header and footer are independent: you can configure either one, both, or neither.
Inline template example
curl -X POST "https://api.pdfcrowd.com/convert/" \
-u "USERNAME:API_KEY" \
-F "src=https://example.com/report" \
-F "header_html=<div>Quarterly report</div>" \
-F "footer_html=<div>Page <span class='pdfcrowd-page-number'></span> of <span class='pdfcrowd-page-count'></span></div>" \
-F "header_height=0.7in" \
-F "footer_height=0.6in" \
-o report.pdfConfirm the endpoint, authentication, and exact request encoding against the current HTTP reference for your account. If HTML contains ampersands, quotes, or other special characters, use a client library or correctly encode the multipart/form fields rather than assembling an unescaped shell string.
Hosted template example
curl -X POST "https://api.pdfcrowd.com/convert/" \
-u "USERNAME:API_KEY" \
-F "src=https://example.com/report" \
-F "header_url=https://example.com/pdf/header.html" \
-F "footer_url=https://example.com/pdf/footer.html" \
-F "header_height=0.7in" \
-F "footer_height=0.6in" \
-o report.pdfHosted templates must be reachable by PDFCrowd’s converter. They should not require an interactive login, and their styles and assets need to load within the conversion environment. Use stable URLs and avoid short-lived signed links unless their validity covers the full conversion.
2. Add page numbers and style the running content
Place pdfcrowd-page-number in the template where the current printed page number should appear, and pdfcrowd-page-count where the total number of printed pages should appear. For example:
<div class="running-footer">
<span>Confidential</span>
<span>Page <span class="pdfcrowd-page-number"></span>
of <span class="pdfcrowd-page-count"></span></span>
</div>Templates can include CSS. Keep the template’s box dimensions consistent with the reserved height, and check the result on a representative document that has several pages. The page count refers to printed pages, so page breaks and print CSS can change the value.
The client method index documents number-format attributes, including a Roman numeral example. Consult the current method reference for your chosen client and the precise supported attribute syntax. The API reference also lists optional CSS annotations for first/last, odd/even, page-number, and page-count-specific styling; those annotations are version-gated to converters at or above 20.10.
3. Reserve space and tune dimensions
header_height and footer_height reserve vertical space on each page for the respective template. The documented default for each is 0.5in. Accepted units include inches, millimeters, centimeters, pixels, and points.
| Setting | Purpose | Practical guidance |
|---|---|---|
header_height |
Space reserved for the header | Increase for multiple lines, larger type, or images. |
footer_height |
Space reserved for the footer | Allow room for both legal text and page numbering if both appear. |
no_header_footer_horizontal_margins |
Lets header/footer width match the physical page width | Use when running content must reach the page edges; listed for converter version 20.10 and later. |
header_footer_scale_factor |
Scales header/footer content | Documented range is 10–500; default is 100. |
Insufficient reserved height can clip the running content or cause it to collide with the main body. Excessive height consumes usable page area and can change pagination, which in turn can change the page count. Tune both dimensions using the longest header/footer variant, not only the simplest page.
4. Exclude headers or footers from selected pages
Use exclude_header_on_pages and exclude_footer_on_pages for comma-separated page numbers. The documented examples include 1,-1 for the first and last pages. Treat this as page-specific suppression of the relevant running element; the other element can remain visible.
# Illustrative HTTP form fields; use the request shape from the API reference
exclude_header_on_pages=1,-1
exclude_footer_on_pages=1For page or range-specific rules, the reference describes conversion_config with pageSetup entries, page selectors, and displayHeader/displayFooter values such as none, space, and content. When JSON conversion configuration explicitly specifies a setting, it takes precedence over the corresponding global option. Consult the reference for the exact JSON structure and supported page selector syntax before using it in production.
5. Resolve conflicts with CSS @page
Source-document print CSS can define page size and margins through @page. PDFCrowd’s css_page_rule_mode controls precedence between API page settings and CSS page rules:
default: API page settings take precedence.mode2: CSS@pagerules take precedence.mode1: legacy behavior for backward compatibility.
If a header appears at an unexpected position or the document body overlaps it, check both the API dimensions and the source page CSS. Change precedence deliberately; otherwise a CSS rule may override the page setup you expect.
6. Use a PDFCrowd client library
PDFCrowd’s method index lists HTML-to-PDF header/footer support for HTTP and client families including PHP, Java, .NET, Python, Node.js, Ruby, Go, CLI, and WordPress. Method names and request syntax vary by client. Use the language’s current official reference for setters corresponding to header/footer HTML or URLs, reserved heights, scale factor, and conversion configuration instead of assuming the HTTP parameter syntax maps one-to-one to a library call.
A safe implementation sequence is:
- Set the source HTML or source URL and confirm a basic PDF conversion works.
- Add one header or footer template, then set its reserved height.
- Add dynamic page values and inspect a multi-page output.
- Add exclusions or per-page conversion configuration if needed.
- Check converter-version requirements for margin and annotation options.
7. Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| Header/footer is clipped | The reserved height is smaller than the rendered template. | Increase header_height or footer_height; include line-height, padding, and image height in the estimate. |
| Body text overlaps the running content | Insufficient reserved space or conflicting page margins/CSS. | Increase the reserved height and inspect source @page rules together with css_page_rule_mode. |
| Page number or total is missing | The expected class is absent, misspelled, or not present in the actual template. | Use pdfcrowd-page-number and pdfcrowd-page-count on elements in the header/footer template; verify the template source returned by a hosted URL. |
| Page count differs from expectation | Pagination changed due to content, paper size, margins, or reserved header/footer space. | Check the printed output and page-break rules; count printed pages, not source sections. |
| Header is absent on a page | A page exclusion or page-specific pageSetup rule suppresses it. |
Review exclude_header_on_pages and any explicit displayHeader value in conversion_config. |
| Global setting seems ignored | Explicit JSON conversion configuration takes precedence for settings it specifies. | Update or remove the overriding pageSetup entry. |
| Edge-to-edge width has no effect | The converter may not support the option’s required version. | Confirm converter version 20.10 or later for no_header_footer_horizontal_margins. |
| Hosted template does not render as expected | The URL is unreachable to the converter, returns different HTML, or depends on unavailable assets. | Serve the template over HTTP/HTTPS without an interactive login; make dependent resources reachable and inspect the returned markup. |
8. Performance, reliability, and cost considerations
Inline templates keep the request self-contained but make request encoding and escaping more important. Hosted templates are reusable, but introduce a network dependency: the converter must fetch the template and its assets. Keep templates small, avoid unnecessary remote resources, and allow for the time needed to fetch them.
Header/footer settings can alter pagination because they reserve space on every applicable page. If exact page count matters, use stable source content, fonts, paper settings, margins, and template dimensions. Recheck representative documents when any of those inputs change. Confirm version-gated features against the converter version in use.
PDFCrowd’s API is a conversion service, so account pricing and any usage limits depend on the provider’s current plan. This research dossier does not establish current prices or conversion benchmarks; check PDFCrowd’s current pricing and account terms before estimating production cost.
9. A related option for screenshot workflows
If your task is to capture a web page as a PDF rather than convert a document with PDFCrowd’s HTML-to-PDF API, ScreenshotNeo is a website screenshot API and MCP server for developers. Its PDF capture options include paper size, margins, landscape, and page ranges; the full option list and request details are in the ScreenshotNeo API documentation.
Or skip the browser setup
For a PDF capture of a web page, ScreenshotNeo can return a PDF from a single request. This runnable cURL example captures a page; adapt the URL to your own page and use the PDF output options documented for the API:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.pdfSee the ScreenshotNeo docs for PDF format parameters and options. Cookie banners, popups, and chat widgets are removed before the shot; bot checks, blank pages, and failed loads are never billed. An MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.
FAQ
Can the header and footer use different templates?
Yes. Configure them independently with their respective HTML or URL parameter and reserved height.
Can I show a header only on some pages?
Yes. Use the page exclusion option for selected page numbers or page-specific display rules in conversion configuration.
Does changing the header height change page count?
It can. Reserved space reduces the area available to the body on each page and may shift content onto additional printed pages.
Can a template contain images or CSS?
Templates can use CSS. For remote templates, ensure referenced assets are reachable by the converter and allow enough reserved height for their rendered size.
