HTML2PDF Web Service

The HTML2PDF Web Service for converting HTML to PDF is available through a HTTP API. Please use this document to get started.

The end-point of the HTTP API is https://app.html2pdfwebservice.com/api/convert and only accepts POST-requests. To tell the web service which page or content to convert to PDF and with what settings you're required to POST a JSON string as the payload. To see which settings are supported please take a look at the Settings-section. Authentication is also required and is explained in the API Authentication-section.

API Authentication

To be able to use our REST API you're required to authenticate yourself. To do so an account is required. In case you don't have an account yet you can sign up for our 14-day free trial. To authenticate against our web service you're required to use your API key and username. These can be found on your profile page and dashboard.

Authentication is done by providing these details in extra HTTP headers as shown below:

$ curl -H "X-API-Key: F8802062-4D31-11E3-8F59-BFD4058B6BFF"
       -H "X-API-Username: MyUsername"
       -d '{"url":"http://domain.com/invoice.html"}'
       https://app.html2pdfwebservice.com/api/convert > invoice.pdf

Settings

For your convenience we've listed all available options on this page.

Rendering engine

We support multiple versions of our rendering engine due to visually different results between engines. By default v1 is used. To use v2 provide the engine parameter like so https://app.html2pdfwebservice.com/api/convert?engine=v2

Mandatory

You're required to either provide the content setting or url setting. The content setting may contain HTML data. If the page to be converted is accessible online use the url setting.

content
Provide any arbitrary HTML content to convert to PDF.
{"content": "<html><body><h1>Hello World!</h1><p>Lorem ipsum</p></body></html>"}
url
The url of the HTML page to be converted to PDF. HTTP authentication is supported through the username and password setting. The url setting has precedence over the content setting.
{"url": "http://html2pdfwebservice.com/documentation"}

Optional

collate
Collate when printing multiple copies
{"collate": true}
no_collate
Don't collate when printing multiple copies
{"no_collate": true}
copies
Number of copies to print in the PDF file
{"copies": 1}
disable_external_links
Do not make links to remote web pages
{"disable_external_links": false}
disable_internal_links
Do not make local links
{"disable_internal_links": false}
disable_javascript
Disable Javascript to not allow web pages to run it. In some cases (mostly with 3rd party vendors) using a lot of Javascript can result in errors.
{"disable_javascript": false}
no_pdf_compression
Do not use losless compression on PDF objects
{"no_pdf_compression": false}
Used to be disable_pdf_compression
disable_smart_shrinking
Disable the intelligent shrinking strategy used by WebKit that makes the pixel/dpi ratio none constant
{"disable_smart_shrinking": false}
dpi
Change the DPI
{"dpi": 100}
encoding
Set the default text encoding for input
{"encoding": "utf-8"}
enable_forms
Turn HTML form fields into pdf form fields
{"enable_forms": true}
footer_content
Put footer on every page. Note that footer content must contain a <!DOCTYPE html> line or otherwise it will not show.
{"footer_html": "<!DOCTYPE html> <p>Footer text</p>"}
footer_html
The url of the HTML page to be used as a footer. The footer_content setting has precedence over the footer_html setting.
{"footer_html": "http://html2pdfwebservice.com/footer.html"}
footer_center
Centered footer text
{"footer_center": "Footer text"}
footer_left
Left aligned footer text
{"footer_left": "Footer text"}
footer_right
Right aligned footer text
{"footer_right": "Footer text"}
no_footer_line
Do not display line above the footer
{"no_footer_line": true}
footer_line
Display line above the footer
{"footer_line": true}
footer_spacing
Spacing between footer and content in mm
{"footer_spacing": 40}
grayscale
PDF will be generated in grayscale
{"grayscale": false}
header_content
Put header on every page. Note that header content must contain a <!DOCTYPE html> line or otherwise it will not show.
{"header_html": "<!DOCTYPE html> <p>Footer text</p>"}
header_html
The url of the HTML page to be used as a header. The header_content setting has precedence over the header_html setting.
{"header_html": "http://html2pdfwebservice.com/header.html"}
header_center
Centered header text
{"header_center": "Footer text"}
header_left
Left aligned header text
{"header_left": "Footer text"}
header_right
Right aligned header text
{"header_right": "Footer text"}
no_header_line
Do not display line below the header
{"no_footer_line": true}
header_line
Display line below the header
{"header_line": true}
header_spacing
Spacing between header and content in mm
{"header_spacing": 40}
lowquality
Generates lower quality PDF to help shrink document space
{"lowquality": false}
margin_bottom
Set the page bottom margin
{"margin_bottom": "10mm"}
margin_left
Set the page left margin
{"margin_left": "10mm"}
margin_right
Set the page right margin
{"margin_right": "10mm"}
margin_top
Set the page top margin
{"margin_top": "10mm"}
minimum_font_size
Minimum font size
{"minimum_font_size": 5}
no_background
Do not print background
{"no_background": false}
orientation
Set the orientation of the document to landscape or portrait
{"orientation": "Landscape"}
{"orientation": "Portrait"}
outline
Put an outline into the PDF
{"outline": false}
outline_depth
Set the depth of the outline
{"outline_depth": 4}
page_height
Page height in millimeters
{"page_height": 500}
page_size
Set paper size to A4 or Letter
{"page_size": "A4"}
{"page_size": "Letter"}
page_offset
Starting page number
{"page_offset": 1}
page_width
Page width in millimeters
{"page_width": 500}
print_media_type
Use print media-type instead of screen
{"print_media_type": false}
password
HTTP Authentication password
{"password": "my secret"}
proxy
Use a proxy
{"proxy": "http://myproxy:8080"}
javascript_delay
Wait some milliseconds for Javascript-redirects
{"javascript_delay": 200}
Used to be redirect_delay
title
The title of the generated PDF file. Defaults to the title of the first document if not specified.
{"title": "My document title"}
username
HTTP Authentication username
{"username": "myname"}
zoom
Page zoom factor
{"zoom": 1.0}

Note: Some styling options such as zoom, page_size, page_width, page_height and orientation will not work if your HTML document contains floating elements.

Pre Processors

Instead of providing HTML you can also provide other markup languages. This only works in cojunction with the content, header_content and footer_content settings. If you make use of the url setting these settings will be ignored.

We support the following markup languages:
None
Wraps your content in a <pre>-element
HTML
The HTML you input will be supercharged. Only provide the contents of the <body>-element, but not the element itself!
Placing a <span class="page"></span> element will show the current page number.
Placing a <span class="topage"></span> element will show the total page count.
Placing a <span class="date"></span> element will show the current date.
Placing a <span class="isodate"></span> element will show the current isodate.
Placing a <span class="time"></span> element will show the current time.
Placing a <span class="title"></span> element will show the title of the current page object.
Placing a <span class="doctitle"></span> element will show the title of the output document.
Markdown
Documentation
Pod
Documentation
Textile
Documentation
BBCode
Documentation
MultiMarkdown
Documentation
MediaWiki
Documentation
Creole
Documentation
reStructuredText
Documentation
Trac
Documentation
AsciiDoc
Documentation

To make use of Preprocessors you only need to provide a few extra options. You can mix & match preprocessors for the header, content and footer of your document. Note that header_content and footer_content will be wrapped inside a <header id="header">-element and <footer id="footer">-element respectively. You can use their ID's to style them.

preprocessors
{"preprocessors":{"content":"Markdown","footer_content":"Textile","header_content":"HTML","style":"* { color: red; }"}}
Ommit any if you don't want them applied {"preprocessors":{"content":"POD"}}
Pass your custom CSS in the style attribute: {"preprocessors":{"content":"Markdown","style":"body { font-family: Verdana; color: red; font-style: italic;}"}}.

HTTP Status codes

Our REST API only has 1 end-point at https://app.html2pdfwebservice.com/api/convert and only accepts POST requests.

200 SUCCESS
Conversion to PDF succeeded. The PDF data will be in the HTTP response body
400 BAD REQUEST
Unable to parse provided payload. Make sure the JSON object has no errors in it. Please refer the configuration documentation to see what datatypes are expected.
403 FORBIDDEN
Authentication failed. Please make sure you're using the correct credentials, you've got an active account with an active subscription and your token limit hasn't been exceeded.
404 NOT FOUND
Please make sure you're doing a POST-request.
406 UNACCEPTABLE
Please provide a payload e.g. {"url": "http://domain.com/invoice.html"}
408 REQUEST TIMEOUT
The conversion took too long and has been cancelled. Inspect the response body to see the current timeout.
412 INCOMPLETE
Please make sure you're providing both X-API-Username and X-API-Key headers.
429 TOO MANY REQUESTS
Rate limiting has been applied to your account. Please lower the amount of requests you send per second. Retry again after the amount of seconds as stated by the Retry-After header.
500 ERROR
An internal server error occurred. Please review the response body and contact us if you run into this error (preferably with the error message).

HTTP Headers

The following headers are added to the response as well.

X-Tokens-Used
The amount of tokens used to generate the PDF document.
X-Tokens-Left
The amount of tokens you have left to use.
X-Tokens-Warning
This header shows up if you've reached your token limit. A hard limit will be applied soon. Make sure to contact support to upgrade your account before that happens.

Examples

Convert from URL

$ curl -H "X-API-Key: F8802062-4D31-11E3-8F59-BFD4058B6BFF"
       -H "X-API-Username: MyUsername"
       -d '{"url":"http://domain.com/invoice.html"}'
       https://app.html2pdfwebservice.com/api/convert > invoice.pdf

Convert Content

$ curl -H "X-API-Key: F8802062-4D31-11E3-8F59-BFD4058B6BFF"
       -H "X-API-Username: MyUsername"
       -d '{"content":"<html><head><title>My page</title></head><body><h1>Hello World!</h1><p>I am an HTML page converted to PDF!</p></body></html>"}'
       https://app.html2pdfwebservice.com/api/convert > page.pdf

Using HTTP Authentication

$ curl -H "X-API-Key: F8802062-4D31-11E3-8F59-BFD4058B6BFF"
       -H "X-API-Username: MyUsername"
       -d '{"url":"http://domain.com/invoice.html", "username": "JohnDoe", "password": "MySecret!"}'
       https://app.html2pdfwebservice.com/api/convert > invoice.pdf

Request token usage and limit

$ curl -H "X-API-Key: F8802062-4D31-11E3-8F59-BFD4058B6BFF"
       -H "X-API-Username: MyUsername"
       -X GET
       https://app.html2pdfwebservice.com/api/usage

Which results in a hash containing the following fields: {"used": 0, "limit": 250}. In case an error occurs it returns an HTTP 500 error. Otherwise when successful it returns an HTTP 200 status.

Using PHP with cURL

$settings = array(
    'url' => 'http://domain.com/invoice.html',
);

$curl = curl_init();
curl_setopt($curl, CURLOPT_POST, 1);
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($settings));
curl_setopt($curl, CURLOPT_HTTPHEADER, array(
    'X-API-Username: MyUsername',
    'X-API-Key: F8802062-4D31-11E3-8F59-BFD4058B6BFF'
));

curl_setopt($curl, CURLOPT_URL, 'https://app.html2pdfwebservice.com/api/convert');
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
// Helps to debug in case of issues
// curl_setopt($curl, CURLOPT_VERBOSE, 1);

// In case the SSL certificate isn't accepted because of outdated certificates
// on your server
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);

$res = curl_exec($curl);
// Save PDF to disk
file_put_contents('document.pdf', $res);
curl_close($curl);

Using Perl with Mojo::UserAgent

#!/usr/bin/env perl
use strict;
use warnings;
use Mojo::UserAgent;

my $ua = Mojo::UserAgent->new;
my $tx = $ua->post(
    'https://app.html2pdfwebservice.com/api/convert' => {
        'X-API-Username' => 'MyUsername',
        'X-API-Key'      => 'F8802062-4D31-11E3-8F59-BFD4058B6BFF'
    } => json => {url => 'http://domain.com/invoice.html'}
);
if (my $res = $tx->success) {
    my $pdf_data = $res->body;
}

Using Ruby

require 'net/https'
require 'uri'

uri           = URI.parse('https://app.html2pdfwebservice.com/api/convert')
https         = Net::HTTP.new(uri.host, uri.port)
https.use_ssl = true
# In case the SSL certificate isn't accepted
https.verify_mode = OpenSSL::SSL::VERIFY_NONE

req = Net::HTTP::Post.new(uri.path)
req['X-API-Username'] = 'MyUsername'
req['X-API-Key']      = 'F8802062-4D31-11E3-8F59-BFD4058B6BFF'
req.body              = '{"url": "http://domain.com/invoice.html"}'

res = https.request(req)
if res.code == '200'
    pdf_data = res.body
    # - or write to file -
    # File.open('invoice.pdf', 'w') { |file| file.write(res.body) }
end

Using node.js

var https = require('https');
var fs    = require('fs');

var data = JSON.stringify({
    'url': 'http://domain.com/invoice.html'
});

var options = {
  host: 'app.html2pdfwebservice.com',
  port: '443',
  path: '/api/convert',
  method: 'POST',
  headers: {
    'Content-Type': 'application/json; charset=utf-8',
    'Content-Length': data.length,
    'X-API-Username': 'MyUsername',
    'X-API-Key': 'F8802062-4D31-11E3-8F59-BFD4058B6BFF'
  }
};

var req = https.request(options, function(res) {
    var msg = '';
    console.log("statusCode: ", res.statusCode);
    console.log("headers: ", res.headers);
    res.setEncoding('utf8');
    res.on('data', function(chunk) {
        msg += chunk;
    });
    res.on('end', function() {
        fs.writeFile('test.pdf', msg, 'binary', function(err) {
            if(err) {
                console.log(err);
            }
        });
    });
});

req.write(data);
req.end();

req.on('error', function(err) {
    console.log(err);
});

Other languages Python, C#, Java

Examples for other languages will follow soon! Got a working example for us to put here? Please contact us!

Token calculation

Every plan offers an amount of tokens to be used when converting documents. When a PDF has been generated its token usage will be calculated. A token is worth 500KB. So if the resulting PDF is 250KB of size it will have used 1 token(s). A PDF with a size of 2048KB will have used 5 token(s).

Limitations and access restriction

We maintain soft and hard limits for token usage. The amount of tokens that your subscription plan offers functions as a soft limit. When your soft limit is exceeded we'll start returning the X-Tokens-Warning header which will notify you of exceeding your usage. Every convert call will return your token usage and remaining tokens as well.

The hard limit is set at 20%*. So if your plan has 500 tokens, the hard limit will be set at 600 tokens. After you've reached the hard limit access to the conversion API will be denied.

Please take care of monitoring your usage. You can retrieve your usage with the API-call /api/usage or by logging in into your control panel. The header X-Tokens-Left will be included with every conversion API-call as well. Contact us before you reach your hard limit to ensure continued service.

* The way the hard limit is calculated may change at any time without notice.

Questions?

Missing anything from the documentation? Do not hesitate to contact us.