Introduction

PDFMark is a REST API for generating PDF documents from HTML. You can convert a URL or a block of HTML text to PDF.

The API can be accessed at
https://api.pdfmark.com


Following API endpoints are available

PDF creation API
https://api.pdfmark.com/pdf

Authentication

Every API call must be authenticated with an API Key. You can find your API key in your account dashboard.

Your API Key is a 32 character alphanumeric string.

The API key can be passed either as a query string parameter named key or as HTTP authorization header named key.

Key as query string parameter
 
https://api.pdfmark.com/pdf?key=YOUR_API_KEY

Key as authorization header
 
curl --header 'key: YOUR_API_KEY' https://api.pdfmark.com/pdf

HTTP Response Codes

The REST API returns following HTTP response status codes.

200 OK
400 Input data error
401 Invalid or missing API Key
402 You have exhausted your monthly conversion limit
404 Endpoint not found
429 Too many requests in a short time
500 Internal server error
504 Server timeout while generating PDF

PDF Creation

The main PDF creation API is at endpoint
https://api.pdfmark.com/pdf


You can POST the following data to the endpoint in JSON format. All parameters are case sensitive and must be passed in lower case.

Required parameters
 
html HTML to be converted to PDF One of the 3 parameters is required
url URL to be converted to PDF
template_id ID of the template to be used to generating the PDF.
You can create templates in your account dashboard.
data Data in JSON format to be used along with the template Required if PDF is to be generated from a template
{
  "url" : "https://en.wikipedia.org/wiki/Special:Random"
}
{
  "html" : "<html><body><h1>Hello World</h1></body></html>"
}
{
  "template_id" : 101,
  "data" : {
    ...
  }
}
Optional parameters - document generation
 
page_size One of the following page sizes:
letter
legal
tabloid
ledger
a0
a1
a2
a3
a4
a5
a6
Default: a4
orientation One of the following values:
landscape
portrait
Default: portrait
width To be provided in px/in/cm/mm eg. 10cm
height To be provided in px/in/cm/mm
margin Single margin value to be applied to all sides
To be provided in px/in/cm/mm eg. 0.5in
Default: 0
margin_left Left margin. To be provided in px/in/cm/mm Default: 0
margin_right Right margin. To be provided in px/in/cm/mm Default: 0
margin_top Top margin. To be provided in px/in/cm/mm Default: 0
margin_bottom Bottom margin. To be provided in px/in/cm/mm Default: 0
print_background Whether the background images should be included in PDF
true
false
Default: true
media Whether to consider screen or print css media queries
screen
print
Default: screen
greyscale Whether to generate the PDF in greyscale
true
false
Default: false
header HTML for the document header Following placeholders can be included in the header and footer
{date}
{title}
{url}
{pagenum}
{totalpages}
footer HTML for the document footer
custom_css Additional custom css to be included on the page, useful while converting a URL to PDF.
Can be raw CSS or a link to a CSS file accesible online.
custom_js Additional custom JavaScript to be included on the page, useful while converting a URL to PDF.
Can be raw JScode or a link to a JS file accesible online.
render_delay Time duration to wait for in milliseconds before rendering the PDF
Useful when you want to give adequate time for execution of any JS code or loading large images.
Default: 0
{
  "url" : "URL_TO_CONVERT_TO_PDF",
  "page_size" : "letter",
  "orientation" : "portrait",
  "margin" : "1in",
  "header" : "<img src='IMAGE_URL'>",
  "footer" : "<div style='text-align: center; font-size: 11px;'>{pagenum} of {totalpages}</div>"
}
{
  "html" : "HTML_TO_CONVERT_TO_PDF",
  "margin_left" : "10cm",
  "margin_right" : "10cm",
  "margin_top" : "15cm",
  "margin_bottom" : "20cm",
  "print_background" : false,
  "custom_css" : ".foo{color: #0066FF}",
  "custom_js" : "URL_TO_JS_FILE",
  "render_delay" : 2000
}
Optional parameters - security
 
user_password Password required to open the PDF document If only user password is provided, there will be no restrictions once the user opens the PDF.

If only owner password is provided, user will not be asked for a password for opening the document but after opening functionality will be restricted based on parameters.
owner_password Password required to restrict functionality of the PDF document
allow_copy Whether user can copy content from the PDF
true
false
Applicable only when owner password is provided

If user and owner passwords are same, there will be no restrictions after user opens the PDF.
allow_print Whether user can print the PDF
true
false
allow_modify Whether user can modify the PDF
true
false
{
  "html" : "HTML_TO_CONVERT_TO_PDF",
  "page_size" : "legal",
  "user_password" : "openit",
  "owner_password" : "secret",
  "allow_copy" : false,
  "allow_print" : true,
  "allow_modify" : false
}
Optional parameters - watermark
 
watermark_text Text to be added as watermark on the PDF
watermark_image URL of the image to be added as watermark on the PDF
watermark_position Position of the watermark. One the following values
top_left
top_center
top_right
middle_left
center
middle_right
bottom_left
bottom_center
bottom_right
Default: center
watermark_position_x Custom position from left
Can be in px/in/cm/mm
Watermark position can be either predefined, specified as watermark_position or custom with X and Y coordinates
watermark_position_y Custom position from top
Can be in px/in/cm/mm
watermark_font Font for the text watermark, accepts common font names If you are using custom font, make sure you include the font file in your HTML or using custom_css parameter.
Default: Courier
watermark_text_size Size of text watermark in points Default: 20pt
watermark_text_color Color of text watermark as common HTML color name or Hex code Default: black
watermark_opacity Value between 0 - 1, 0 is completely translarent, 1 is opaque Default: 0.5
watermark_image_width Width of the image watermark in pixels
watermark_image_height Height of the image watermark in pixels
watermark_text_bold Whether to make the watermark text bold
true
false
Default: false
watermark_text_italic Whether to make the watermark text italic
true
false
Default: false
{
  "html" : "HTML_TO_CONVERT_TO_PDF",
  "margin_top" : "1in",
  "watermark_text" : "CONFIDENTIAL",
  "watermark_position" : "top_center",
  "watermark_text_size" : "30pt",
  "watermark_opacity" : 0.8,
  "watermark_text_bold" : true
}

Optional parameters - email delivery

PDFMark can email the generated PDF to the end user. You can specify following parameters for email delivery of the PDF. The PDF will be sent as an attachment in the email. You can specify the recipients of the email, subject and the email body.
 
email_to Email id to send the PDF to. Multiple email ids can be provided separated by a comma ( , )  
email_cc Email id to CC the PDF to. Multiple email ids can be provided separated by a comma ( , )  
email_bcc Email id to BCC the PDF to. Multiple email ids can be provided separated by a comma ( , )  
email_subject Subject of the email Default: Your PDF document
email_body Main body of the email, you can include HTML Default: Please find attached your PDF document

Optional parameters - others
 
temporary When true, the PDF will not be stored on the cloud and will be deleted from our server after 15 minutes
true
false
Default: false
sandbox When true, the PDF will be rendered with PDFMark watermark and will not be counted towards your monthly usage limit, to be used for testing while you are integrating the API in your code
true
false
Default: false
output Output format
pdf
jpg (coming soon)
png (coming soon)
Default: pdf
webhook URL to call after PDF has been generated. The webhook callback will be a POST request with a variable named pdf containing the URL of the PDF. Default: false
{
  "template_id" : 101,
  "data" : {
    ...
  },
  "user_password" : "password",
  "temporary" : true,
  "sandbox" : true
}

Header & Footer

You can add header and footer to the document by specifying the content for header and footer in standard HTML. Do keep in mind certain things though

Always surround your header and footer content in a div or table with 100% width.
"header" : "<div style='width:100%'> ... </div>"
Only use inline styles for header and footer, or specify their styles in the header and footer content.
"header" : "<style> .cls1 { color: blue; } </style> <div style='width:100%' class='cls1'> HELLO WORLD </div>"
You must specify adequate margins while using header and footer.
{
  "header" : "<div style='width:100%; font-size: 14px;'> HELLO WORLD </div>",
  "margin_top" : "1in"
}
To align the header/footer content left/center/right, surround it with a div with 100% width and use the text-align property.
"footer" : "<div style='width:100%; text-align: right; padding: 10px;'> {pagenum} of {totalpages} </div>"
When using images in header and footer, specify the image dimensions explicitly.
<div style='width:100%;'> <img src='http://example.com/logo.png' style='width:100px; height: 30px'> </div>
Avoid referencing external CSS, font or JS files in header and footer content.

Using Templates

If there is a document that you need to generate repeatedly with a fixed format but with different data like an invoice or a ticket or a certificate, then instead of creating the entire HTML yourself and sending it every time, you can create a template and only pass the data for placeholders in the template. You can create a template from your account dashboard.

In order to generate a PDF from a template, you need to send two things – template id and data for placeholders. You can get the id of the template from your account. Data for placeholders need to be sent in JSON format.

The data has to be a JSON object with properties mapped to placeholders in the template HTML.

For instance, if your template is
<div>
  Customer: <br>
  {name}<br>
  {address}<br>
  {phone}
</div>
Then the data for the same has to be passed as
{
  "template_id" : 123,
  "data" : {
    "name" : "Jane Doe",
    "address" : "Some street, some ave <br> city, state - zip",
    "phone" : "123-456-7890"
  },
  "page_size" : "a3"
}
If there is a part of your template that has to be repeated like the items of an invoice or names of attendees in a ticket, then you can surround such data in a <repeat>...</repeat> tag. Name of property which will contain the array of objects for the placeholders in the repeated block is to be provided as attribute named property.
<repeat property="items">
  <tr>
    <td>{product_name}</td>
    <td>{quantity}</td>
    <td>{unit_price}</td>
    <td>{total}</td>
  </tr>
</repeat>
Providing data for the repeated block
{
  "template_id" : 123,
  "data" : {
    "items" : [
      {
        "product_name" : "Product 1",
        "quantity" : 3,
        "unit_price" : "12.00",
        "total" : "36.00"
      },
      {
        "product_name" : "Product 2",
        "quantity" : 1,
        "unit_price" : "20.00",
        "total" : "20.00"
      }
    ]
  }
}
This will generate the following HTML for the PDF
<tr>
  <td>Product 1</td>
  <td>3</td>
  <td>12.00</td>
  <td>36.00</td>
</tr>
<tr>
  <td>Product 2</td>
  <td>1</td>
  <td>20.00</td>
  <td>20.00</td>
</tr>

Inserting QR Code

You can insert a QR code in your documents by enclosing the text in <qr>...</qr> tags. The text between the tags will be converted to a QR code.

For instance, the following code
<qr>https://pdfmark.com</qr>
will be converted to

You can specify the size of individual pixel of QR code with an attribute named pixelsize. Default size is 4.
<qr pixelsize="10">mailto:john.doe@example.com</qr>
will generate

You can include this qr tag within the body of your HTML or template. You can also use it as a placeholder and provide the value of the QR code as a placeholder.

Sample Code

Php
C#
Python
NodeJS
Ruby
Go
VB.Net
Java
$api_key = 'YOUR_API_KEY';
$api_url = 'https://api.pdfmark.com/pdf';
$payload = '{
  "url" : "URL_TO_CONVERT"
}';

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_HTTPHEADER => array(
    'key: ' . $api_key
  ),
  CURLOPT_URL => $api_url,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => $payload
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;