html/2/pdf
The html/2/pdf-endpoint converts an HTML document into a PDF. The source HTML can be provided as a URL or as a string. A variety of options control the output and layout of the generated PDF. In addition to the conversion, the resulting PDF can be watermarked with overlays (text, image or barcode). Finally, headers and footers can be added, e.g. to display page numbers or the current date.
This endpoint is intended for conversion of medium sized PDFs with no more than 100 pages or so. As such it is best used for conversion of letters, reports, contracts, receipt, invoices and similar document types to PDF. It is not suitable for scraping and will not try to pass captchas, cookie banners etc.
NEW: Video tutorial
Endpoint: 'https://api.pdfteam.com/api/html/2/pdf'
Method: 'POST'
Cost: 1
Params:
{
job: string;
user: string;
key: string;
test?: boolean;
inputOptions: InputOptions;
outputOptions?: OutputOptions;
pdfOptions?: PDFOptions;
hfOptions?: HFOptions;
overlays?: [OverlayOptions];
}
// job: an arbitrary string to identify this job, see return value
// user: user name, see section 'API Access' in your account
// key: API key, see section 'API Access' in your account
// test: if TRUE, the API call will not consume credits. PDFs created
// in test mode carry a watermark, default: FALSE
Returns:
{
endpoint: string;
job: string;
credits: number;
result: string;
}
// endpoint: 'html/2/pdf'
// job: same as above
// credits: number of credits consumed
// result: permalink to the PDF in S3 or a base64 encoded string
NOTE: "Test" mode is intended to dial in settings and options. Currently there are no hard limits on this feature. However, abusing "Test"-mode may lead to account termination, please see our terms.
with InputOptions:
InputOptions {
source?: string;
data: string;
}
// source: must be a fully qualified, publicly accessible URL (fetch timeout: 10sec.)
// data: an HTML string, "<html/>...</html>"
//
// If both params are given, source has precedence
//
// NOTE: If the source is not accessible or the HTML can't be rendered, the endpoint
// will return a 400 status code with an error message
with OutputOptions:
OutputOptions {
storage?: boolean;
file?: string;
}
// storage: if TRUE, write file to S3, else return PDF as base64, default: TRUE
// file: file name for document in S3, default: random uuid (v4)
//
// NOTE: File name must not contain '/' or ':'
with PDFOptions:
PDFOptions {
format?: string;
landscape?: boolean;
margin?: {
top?: string;
left?: string;
bottom?: string;
right?: string;
},
};
// format: "A2" | "A3" | "A4" | "A5" | "A6" | "Letter" | "Legal" | "Ledger", default: "A4"
// landscape: if TRUE, set output to landscape, default: FALSE
// margin.*: specify as cm, mm or inches (e.g. "10mm", "0.5in" etc.), default: "1.27cm"
with HFOptions:
HFOptions {
header?: string;
footer?: string;
}
// Specify a HTML template, e.g. "<div>Some Text</div>"
// Use the following classes for dynamic content:
// "date": print date
// "title": document title
// "url": location
// "pageNumber": current pageNumber
// "totalPages": total pages in document
//
// Examples:
// Display page numbers:
//
// <div><span class="pageNumber"></span> of <span class="totalPages"></span></div>
//
// Use CSS to style the text; display document title, center on page:
//
// <div style="font-size: 12px;margin-left:auto;margin-right:auto;">Title: <span class="title"></span></div>
NOTE: Always specify header and footer even if you only need either; simply set the unused component to "nbsp;".
PDF with second example when used for header:
with OverlayOptions:
OverlayOptions {
type: string;
position?: {
x: string;
y: string;
};
firstPageOnly?: Boolean;
rotate?: number;
config: TextConfig | ImageConfig | BarcodeConfig;
}
// type: "text" | "image" | "barcode"
// position.*: specify as cm, mm or inches (e.g. "10mm", "0.5in" etc.), default: x=0, y=0
// position.x: specify as "left" | "center" | "right"
// position.y: specify as "top" | "middle" | "bottom"
// firstPageOnly: if TRUE, put overlay on first page only, default: FALSE
// rotate: rotate by degrees, positive values rotate CCW, default: 0
Currently supported are three types of overlays for the created PDF: text, image, barcode. It's permitted to mix overlays and to have more than one overlay of a given type. Each overlay has a dedicated config section.
with TextConfig:
TextConfig {
data: string;
size?: number;
font?: string;
color?: string;
opacity?: number;
}
// data: the text to display
// size: fontsize in pt, default: 36pt (= 0.5in.)
// font: the API currently supports the standard PostScript fonts:
//
// - 'Times Roman'
// - 'Times Roman Bold'
// - 'Helvetica'
// - 'Helvetica Bold'
// - 'Courier'
// - 'Courier Bold'
//
// default: 'Helvetica'
// color: RGB in CSS style, e.g. '#FF0000', default: '#000000'
// opacity: 0-1, with 0 being fully transparent, default: 1
with ImageConfig:
ImageConfig {
source: string;
}
// source: must be a fully qualified, publicly accessible URL (fetch timeout: 10sec.)
//
// Supported are images in PNG (with transparency) and JPG formats. Best results will
// be with 72dpi images with a max. pixel size that roughly corresponds to the size
// of a PDF page in points. E.g., with an A4 PDF the width is 595pt. Then, the image
// shouldn't be larger than about 600x600px.
with BarcodeConfig:
NOTE: Section below is only an excerpt of all available configuration options for barcode creation; all other parameters will be at reasonable defaults for most users. For a more thorough treatment see the barcode reference.
BarcodeConfig {
type?: number;
data: string;
}
// type: one of the following:
//
// EAN 8 = 0
// EAN 13 = 1
// ISBN 10 = 2
// ISBN 13 = 3
// ISSN = 4
// UPC-A = 5
// UPC-E = 6
// Code 128 = 7
// Code 128 GS1 = 8
// Code 2/5 Interleaved = 9
// Code 2/5 Standard = 10
// ITF-14 = 11
// Code 39 = 12
// PZN = 13
// Laetus = 14
// Codabar = 15
// Datamatrix = 16
// Datamatrix GS1 = 17
// PDF417 = 18
// QR = 19
// Aztec = 20
//
// default: 19 (QR)
// data: data to be encoded into the barcode. With QR, this will usually be a fully
// qualified URL, e.g. 'https://pdfteam.com'. For other barcode types see the
// requirements in the link above.
Code sample (NodeJS with fetch)
Following is a code sample that converts an HTML document into a PDF. The snippet sets input, output and PDF options and defines three overlays: one with text, one with a company logo and one with a QR code:
// Sample code for accessing the PDFTeam API, endpoint: html/2/pdf
const url = 'https://api.pdfteam.com/api/html/2/pdf';
let params = {
job: '00012345',
user: 'YOUR_USERNAME',
key: 'YOUR_APIKEY',
inputOptions: {
source: 'https://pdfteam.com/samples/invoice.html',
},
outputOptions: {
storage: true,
file: 'converted_invoice.pdf',
},
pdfOptions: {
format: 'Letter',
},
overlays: [
{
position: {
x: 'left',
y: '30mm',
},
type: 'barcode',
config: {
type: 19,
data: 'https://pdfteam.com'
},
},
{
rotate: 45,
position: {
x: 'center',
y: 'middle',
},
type: 'text',
config: {
data: 'PAST DUE',
font: 'Helvetica Bold',
size: 72,
color: '#ff0000',
opacity: 0.5,
},
},
{
position: {
x: '132mm',
y: '228mm',
},
type: 'image',
config: {
source: 'https://pdfteam.com/samples/acme_logo.png',
},
},
],
};
fetch(url, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify(params),
}).then((result) => {
result.text().then((text) => {
console.log(text);
});
});
Sample response:
{
'endpoint':'html/2/pdf',
'job':'00012345',
'credits':1,
'result':'https://pdfteam.s3.eu-north-1.amazonaws.com/.../converted_invoice.pdf'
}
Sample result:
More code samples
PDF API Endpoint html/2/pdf sample: Python
PDF API Endpoint html/2/pdf sample: Rust
PDF API Endpoint html/2/pdf sample: C#
PDF API Endpoint html/2/pdf sample: PHP