HTML to PDF API

We offer a professional API for webpage or HTML to PDF conversion. It lets you create high-quality PDF documents quickly, efficiently and cost-effectively. Use it to create high-quality invoices, reports, tickets, e-books, brochures and much more!

Features

  • Supports full HTML with JavaScript, including modern frameworks like Bootstrap.
  • Has many options for PDF layout, headers and footers and much more!
  • Can add watermarks, stamps and/or (full) page backgrounds.
  • Can encrypt and protect your PDF documents.
  • Can convert web pages in your secure members area or local intranet.
  • Can convert or exclude parts of a webpage
  • Ready to use code examples for .NET / C#, Java, JavaScript, PHP, Perl, Ruby, Python and VB.net!
  • No installation required, but we do have a .NET component and a PHP library available!

Basic Usage

The PDFmyURL API is easy to use. It takes a license and either a URL or raw HTML as input and returns the PDF.
You just send a request similar to this, which converts http://www.example.com to PDF:

https://pdfmyurl.com/api?license=yourlicensekey&url=http://www.example.com

The request should at least have the following components:

  1. endpoint: this should be http://pdfmyurl.com/api or https://pdfmyurl.com/api for secure access
  2. license: this is mandatory and you will get yours when you sign up
  3. url: the web page that you want to convert OR
  4. html: the raw HTML code that you want to convert

By default we will use all the conversion defaults you set in our members area. Other than that you can use a lot of additional parameters in the API call, which give you access to all the features for conversion. These are all specified below.

NB: You can use both GET as well as POST requests as long as you properly URL encode the data that you pass.

Setting Options

The sections below describe all the options that you will be able to use with the API. Just attach each parameter to the request.
Example: If you want a PDF in A4 format and portrait orientation, you would use the following request.

https://pdfmyurl.com/api?license=yourlicensekey&url=http://www.example.com&page_size=A4&orientation=portrait

Page Dimensions

The table below shows the settings that you can change to control the page settings. These will determine the layout of the resulting PDF.

ParameterDescription
page_sizePage size, such as A4, Letter etc. See the full list for details.
orientationPortrait or Landscape orientation
widthWidth of the page in unit
heightHeight of the page in unit.
If you specify a width, but not a height, then we generate one long single page PDF.
topTop margin in unit
bottomBottom margin in unit
leftLeft margin in unit
rightRight margin in unit
unitMeasurement unit, which is applied to the margins as well as the width and height. This can be mm (millimeters), in (inches) or pt (points). The default is millimeters.

Viewport Dimensions new

Our latest rendering engine has two parameters that let you determine at which screen size / viewport we grab the page. This can be useful if you want to grab the mobile version of a webpage or a desktop version at e.g. 2048*1024. Please note that this functionality is currently in beta.

ParameterDescription
screen_widthWidth of the screen - by default this is 1024
screen_heightHeight of the screen - by default this is 768

Conversion Parameters

The table below shows the settings that you can change to control the conversion process. These will largely determine the contents of the resulting PDF.

ParameterDescription
contentControls which content of the page you want to convert or exclude. See part of page conversion for more info.
cssUse custom CSS to style the page to your needs
css_media_typeUse print for the print friendly layout (CSS media type 'print') if your web page has one
bookmarksConvert the headers <h1> through <h4> to bookmarks in your PDF so you click through to those different sections.
zoom_factorUse this zoom factor during conversion, this may alter/improve font kerning e.g. 1.03 for a 3% zoom
grayscaleConvert to a grayscale PDF
no_backgroundDo not show the web page background in the PDF
no_imagesDo not include any images from the web page in the PDF
no_external_linksDo not show hyperlinks to other domains in the PDF
no_internal_linksDo not show hyperlinks within the domain in the PDF
no_javascriptConvert the page with JavaScript switched off
javascript_timeWait this time in milliseconds for JavaScript to complete, default is 200
titleSet the title of the PDF instead of the value of the <title> tag from the web page
filenameSet the filename of the PDF, which you see in the top bar when you open the PDF in Adobe Reader.
tocInclude a table of contents at the beginning of the PDF.

Header and Footer settings

The header and footer can be specified in HTML and we also support extra parameters for dates and page numbers. Have a look at the extensive documentation.

ParameterDescription
headerHTML that you want to use as header
footerHTML that you want to use as footer
page_offsetNumber that will be added to the page number, by default this is 0 so page numbers will start at 1.
Example: set this to -1 if you want the page numbers to start at 0.

Watermarking and Stamping

You can use your own image or text as watermark or stamp for the PDFs that you create. We treat watermarks and stamps as the same thing, because we always place them in the foreground. When you use an opacity of 1 your image will appear as a stamp, otherwise it will look like a watermark.

Watermarks are inserted over the contents of the page only, not over the margins. You can adjust this by using negative positions if you want.

ParameterDescription
wmURL of the watermark image
wm_textText to use as watermark. This will only be used if you don't specify a watermark image.
wm_fontFont face for the text watermark e.g. Tahoma or Courier
wm_fontsizeSize in points for the text watermark
wm_fontcolorColor for the text watermark, use e.g. #FF0000 for a red text
wm_xThe horizontal position for the watermark
wm_yThe vertical position for the watermark
wm_sxThe horizontal scaling factor for the watermark
Example: use 2 if you want to appear your watermark twice as wide
wm_syThe vertical scaling factor for the watermark
wm_opacityOpacity between 0 and 1. Default is 1, which is fully opague and shows the watermark as a stamp
wm_angleAngle of rotation between 0 and 360

Page background

You can use your own images as the background for the PDFs that you create. Because a lot of users want this functionality to create the resemblance to company stationary, we give you the option to use three different images - one for the first page, one for the middle pages and one for the last page. Obviously you can just use only only for all pages as well if you want.
You can also let us scale the background so that it automatically makes up the whole width and/or height (including margins) so you don't have to worry about positioning it correctly.

Backgrounds are by default put behind the page, including the margins. This also allows you to get your own PDF background color, by using a 1 pixel image with the color of your choice for example.

ParameterDescription
bgURL of the background image, used for the first page (and other pages if bg2 or bg3 are not specified)
bg2URL of the background image, used from the second page onwards
bg3URL of the background image, used for the last page
bg_xThe horizontal position for the background
Default is 0, which is the absolute left of the page
bg_yThe vertical position for the background
Default is 0, which is the absolute top of the page
bg_sxThe horizontal scaling factor for the background
If you use 0 then we will scale to the full width of the page
bg_syThe vertical scaling factor for the background
If you use 0 then we will scale to the full height of the page
bg_opacityOpacity between 0 and 1. Default is 1, which is fully opague
bg_angleAngle of rotation between 0 and 360

PDF encryption and rights management

You can use the encryption settings (also known as PDF rights managements or PDF document security) from the table below. This allows you to control who will be able to open a PDF, print it and more. Just make sure that your version of Acrobat Reader (or other PDF reader) supports the level of encryption that you choose, so you can actually OPEN the resulting PDF!

ParameterDescription
encryption_levelLevel of encryption of the PDF, which accepts the following values:
  • 40: 40-bit RC4
  • 128: 128-bit RC4
  • 128aes: 128-bit AES
  • 256: 256-bit AES
user_passwordPassword needed to open the PDF
owner_passwordPassword needed to adjust the rights management settings of the PDF
no_printPrevent users from printing the PDF
no_copyPrevent users from copying content from the PDF
no_modifyPrevent users from annotating (commenting) the PDF

Accessing secure sites and/or member areas

We understand that your content may reside in a protected area on your site. If you still want to convert this to PDF, we have the following options for you.

  1. Log into your site from our members area or by using our login API - we will then use the stored cookies for all your conversions.
  2. Pass the page as raw HTML with the html parameter instead of using the url parameter. In that way we don't need to access your page. You can of course use https to access our API to ensure your data is secure. We have created a JavaScript example that demonstrates how you can do this quickly.
  3. Secure your content with basic HTTP authentication and specify the username and password parameters in the API call.
  4. Secure your content with a login form and pass the form fields and values to the API so we can login to your site.
  5. Use cookies on your site (in combination with other measures) to identify legitimate access to your page and pass a cookie jar with cookies. You can also pass a cookie jar in the old Netscape format, which is the format that tools like cURL and wget will generate.
  6. Contact us to discuss other options or ask us to use a specific access routine.
ParameterDescription
usernameUsername for basic HTTP access authentication
passwordPassword for basic HTTP access authentication
form_urlURL of a login page that you want us to use and post the form_fields to
form_fieldsArray with form fields and values that you want us to post to the login page, so we can login to your site
session_idThe contents of a JSESSIONID cookie, that we should use to access your URL
cookie_jarThe contents of a cookie jar file, that we should use to access your URL
ns_cookie_jarThe contents of a cookie jar file in the old Netscape format (still used by cURL and wget), that we should use to access your URL

Accessing secure sites with the login API

If you want to login to your members area regularly, for example when your cookies expire, then it's easiest if you use our login API. The login API logs in to your members area and then stores the cookies in your settings so they will automatically be used in all conversions for your plan.

It works the same as logging in from our secure login page in the members area or as passing the login parameters to our API, but the advantage is that it saves time and you only need to log in whenever you really want to.

To use the login API you send a request similar to:

https://pdfmyurl.com/login_api?license=yourlicensekey&form_url=http://www.example.com/login.aspx&form_fields[user]=xxx&form_fields[password]=xxx

The request should at least have the following components:

  1. endpoint: this should be http://pdfmyurl.com/login_api or https://pdfmyurl.com/login_api for secure access
  2. license: this is mandatory and you will get yours when you sign up
  3. form_url:Your login page, typically something like http://www.example.com/blog/wp-login.php
  4. form_fields:An array with form fields and values that we will POST to the login page, for example form_fields[username]=user
  5. output: json or text output. This parameter is optional and by default we assume you want a JSON response.

The output that you will receive will be a either an error message or the values of the cookies that we have stored. Note that we will NOT store the login parameters in our database, but only the returned cookies. We do this to protect your privacy.

Example - WordPress login with the PDFmyURL API

With the form_url and form_fields parameters you will be able to let us log in to your site. Just make sure that you specify all the form fields that are actually required to be posted. As an example, here's what you would typically use for a login to a WordPress site.

ParameterDescription
form_urlYour login page, typically something like http://www.example.com/blog/wp-login.php
form_fields[log]The username of your WordPress user
form_fields[pwd]The password of your WordPress user

Please note that the login API is currently only available with a paid license.

Return codes

Our API returns HTTP response codes, which you can check to see if the conversion was succesfull or not. The following is the list of return codes we use.

CodeDescription
200 OKYour conversion was processed succesfully
400 Bad RequestYou didn't specify anything to convert
401 Authorization requiredYou specified an invalid license key
429 Too Many RequestsYou have overrun a usage limit for your plan
503 Service unavailableYou are sending multiple requests at the same time to the API from the same IP address

Usage tracking

You can track your PDFmyURL usage via a separate HTTP request. This request by default will give you a JSON response indicating plan details and usage.

Just send a request similar to:

https://pdfmyurl.com/usage?license=yourlicensekey

The request should at least have the following components:

  1. endpoint: this should be http://pdfmyurl.com/usage or https://pdfmyurl.com/usage for secure access
  2. license: this is mandatory and you will get yours when you sign up
  3. output: json or text output. This parameter is optional and by default we assume you want a JSON response.

The output that you will receive will look something like this. Please be aware that we may add fields to the structure in the future!

array (
  'plan' => 
  array (
    'start' => '2013-04-15',
    'end' => '2014-07-15',
    'description' => 'Business License - Advanced',
    'limit' => '5000',
    'limit period' => 'month',
    'status' => 'blocked',
  ),
  'usage' => 
  array (
    'today' => '65',
    'current period' => '5002',
    'all time' => '95014',
  ),
)

Note that our date fields are all in the format yyyy-mm-dd and the 'status' field in the 'plan' array will indicate if your plan is 'active' or 'blocked'.