# Introduction
The Docamatic API is a RESTful API based on HTTPS requests and JSON responses. The API allows you to:
- Generate PDFs from a URL or HTML
- Generate PDFs or images from templates
- Generate images from a URL or HTML
# Quick Start
Here are some code samples to get you started. All requests must be made over HTTPS and must contain your API key in the header as a bearer token.
curl -X POST https://docamatic.com/api/v1/pdf \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d source="https://news.ycombinator.com" \
-d format=A4 \
-d media=print \
require 'net/https'
require 'uri'
require 'json'
uri = URI('https://docamatic.com/api/v1/pdf')
response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
request = Net::HTTP::Post.new(uri)
request.content_type = 'application/json'
request['Authorization'] = "Bearer #{ENV['DOCAMATIC_API_KEY']}"
request.body = JSON.generate(
'source': 'https://news.ycombinator.com',
'format': 'A4',
'media': 'print'
)
http.request(request)
end
puts response.body
# pip install requests
import os
import requests
data = {
'source': 'https://news.ycombinator.com',
'format': 'A4',
'media': 'print'
}
response = requests.post('https://docamatic.com/api/v1/pdf', json=data, "Bearer {os.getenv('DOCAMATIC_API_KEY')}")
print(response.json())
$headers = [
'Authorization: Bearer YOUR_API_KEY',
'Content-Type: application/json'
];
$data = [
'source' => 'https://news.ycombinator.com',
'format' => 'A4',
'media' => 'print'
];
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://docamatic.com/api/v1/pdf');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
$response = curl_exec($ch);
curl_close($ch);
var_dump(json_decode($response), true);
# use Illuminate\Support\Facades\Http;
$response = Http::withToken(config('services.docamatic.key'))->post('https://docamatic.com/api/v1/pdf', [
'source' => 'https://news.ycombinator.com',
'format' => 'A4',
'media' => 'print'
]);
$data = $response->json();
dd($data);
// npm install node-fetch
const fetch = require("node-fetch");
const url = "https://docamatic.com/api/v1/pdf";
const token = new Buffer(process.env.DOCAMATIC_API_KEY + ":").toString("base64");
async function convert() {
const response = await fetch(url, {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
source: "https://news.ycombinator.com",
format: "A4",
media: "print"
})
});
const json = await response.json();
console.log(json);
};
convert();
# Testing With Postman
Postman is an excellent tool for API testing. We recommend it for making test requests and familiarising yourself with the Docamatic API. You can download it for free at https://www.getpostman.com/downloads .
Below are screenshots demonstrating how to use postman with the Docamatic API. Check out https://learning.getpostman.com for official documentation.
1. Create a new request and define authorization settings.

2. Set the headers.

3. Set the request body and send.
Remember to set "test" to true so that you don't use up your production credits.

# Authentication
The Docamatic API uses API keys to authenticate requests. You can obtain your API key from the API Key page, found here: Go to My account
Your API key is like a password - please keep it secure
Authentication to the API is performed using the Bearer Token method in the Authorization header. All API requests must be made over HTTPS.
Authorization: Bearer YOUR_API_KEY
# Rate Limiting
By default access is limited to 120 requests per minute. When reaching the rate limit you will receive a HTTP status code of 429 . If you need to make more than 120 requests per minute please contact support.
# Response Codes
The status of a response can be determined from the HTTP status code.
Code | Status | Description |
---|---|---|
200 | OK | Request successful |
400 | Bad request | Request was invalid |
401 | Unauthorized | User does not have permission |
403 | Forbidden | Request not authenticated |
405 | Method Not Allowed | Incorrect HTTP method provided |
415 | Unsupported Media Type | Response is not valid JSON |
422 | Unprocessable Entity | Valid JSON but error encountered |
429 | Too Many Requests | Client is rate limited |
500 | Internal Server Error | Server error, please try again later or contact support |
# Document Storage
Docamatic gives you full control over how long your documents should be stored. If your document is returned as base64 it is not persisted to storage.
You can configure how long documents should be stored through your dashboard: Go to Account Settings .
For those on a free plan, documents can be stored for up to 48 hours. Customers on a paid plan can store documents for up to 14 days.
If you make use of Docamatic's cloud storage, all documents are deleted forever after your desired storage period. You can delete a document at any time using the delete endpoint.
Save to your own Amazon S3 bucket
Docamatic also allows you to save documents directly to your own Amazon S3 bucket. This simplifies the integration process and also ensures data privacy.
You need to update the bucket policy to allow Docamatic write permissions. You can obtain a sample policy from the dashboard: Get S3 Bucket Policy .
After the bucket policy has been defined you can specify the s3 parameter in your request. The s3 parameter requires the region in which your bucket is located and the bucket name. The path parameter is non mandatory.
Example request:
{
"source": "https://my-site.com/invoice.html",
"s3": {
"region": "us-east-1",
"bucket": "mybucket",
"path": "invoices"
}
}
# Integrations
Docamatic's integration with Zapier allows you to easily connect with thousands of other apps. The integration allows you to convert HTML to PDF and to perform actions on newly created documents: Setup Zapier Here
# Endpoints
The Docamatic API is accessed by making HTTPS requests to a specific version endpoint URL. The base URL for the API is: https://docamatic.com/api/v1 . The following endpoints are available:
URL | Method | Description |
---|---|---|
POST | Generate a PDF document from a URL or HTML | |
/template | POST | Generate a PDF or image from a template |
/image | POST | Generate an image from a URL or HTML |
/delete | DELETE | Delete a document or image from storage |
/credits | GET | Get a summary of API usage for the current billing period |
This endpoint allows you to generate a PDF document from a URL or HTML. The source parameter is the only mandatory body parameter. All other parameters are optional. Example requests can be found below this table.
Parameter | Type | Description |
---|---|---|
source | string | A valid URL or HTML. |
media | string | Generate PDF using screen or print css media. Valid values are screen or print. |
format | string | Paper format. If set, takes priority over width or height options. Valid values are Letter, Legal, Tabloid, Ledger, A0, A1, A2, A3, A4, A5. |
margin_top | number | Top paper margin. |
margin_right | number | Right paper margin. |
margin_bottom | number | Bottom paper margin. |
margin_left | number | Left paper margin. |
margin_unit | string |
Unit of measurement for margins. Possible values are:
|
width | number | Paper width. If format set, it takes priority over width. |
height | number | Paper height. If format set, it takes priority over height. |
unit | string |
Unit of measurement for width and
height. Possible values are:
|
landscape | boolean | Paper orientation. |
test | boolean | Create a test document that does not reduce your production credits. Document created will have a "sample" watermark. |
encode | boolean | Return the document as a base64 encoded string. Documents over 4MB cannot be returned as base64. If over 4MB a URL will be returned instead. |
webhook | string | A valid URL where we will send a POST request containing a JSON result. Your webhook should return a 200 status code. |
zoom | number | Scale of the webpage rendering. Defaults to 1. Zoom amount must be between 0.1 and 2. |
disable_backgrounds | boolean | Don't print background graphics. |
grayscale | boolean | Generates the document in grayscale. |
header_footer | boolean | Display header and footer. |
header_template | string |
HTML template for the print header. Should be valid HTML with following classes used to inject printing values into them:
|
footer_template | string | HTML template for the print footer. Should use the same format as the header_template . |
page_numbers | boolean | Insert page numbers into the footer of each page. Ignored if footer_template has been set. |
css | string | A valid URL pointing to a CSS file or a valid CSS string. Allows CSS to be injected to the page before the document is generated. Please note if supplying a URL to a CSS asset it must be publicly accessible. |
prefer_css_page_size | boolean | Give any CSS @page size declared in the page priority over what is declared in width and height or format options. Defaults to false, which will scale the content to fit the paper size. |
page_ranges | string | Paper ranges to print, e.g., '1-5, 8, 11-13'. Defaults to the empty string, which means print all pages. |
accept_cookie_warning | boolean | Accept cookie consent notifications prior to generating the document. Unable to target all notifications by default but works for most. See click_elements for manual targeting. |
click_elements | array | Click button or link elements. You can specify which elements to click by specifying the element's CSS class name or the text value of the element. For example, clicking two elements, one by text value and the other by class name: ["Button Text", ".button-class"] |
name | string | A descriptive name for your document, visible from within the dashboard. |
auth | object |
Allows a document to be created if source URL has been protected behind basic HTTP authentication. Requires:
|
s3 | object |
Allows you to save directly to your own Amazon S3 bucket. Requires:
|
object |
Send the generated document as an email attachment or download link.
Maximum attachment size is 9MB. If document exceeds 9MB or you are using your own S3 bucket, a link will be sent in the email body instead. Please note that download links are only valid whilst document remains in storage.
|
# PDF Example 1
The following request will create an A4 document using a URL passed via the source parameter. We have set the media type to print so that the resulting document will be generated using the CSS print rules that have been defined at this URL. We have set top and bottom margins on the page. As we did not specify margin_unit , margins will use default unit cm. By providing the email parameter, the resulting document will ALSO be sent via email as an attachment.
{
"source": "https://news.ycombinator.com",
"format": "A4",
"media": "print",
"margin_top": 2,
"margin_bottom": 2,
"email": {
"to": "john.smith@my-company.com",
"subject": "PDF attached"
}
}
{
"document": "https://docamatic.s3.eu-west-1.amazonaws.com/48jKiT339w/11262019/341d581a-e6cf341a364e.pdf",
"size": "85.79 KB",
"success": true,
"transaction_id": "341d581a-fe8c-425b-9c8c-e6cf341a364e"
}
# PDF Example 2
The following example request will create a 4x6 inch PDF test document using HTML passed via the source parameter. By setting the encode parameter to true, we will receive the resulting document as a base64 string.
{
"source": "<html>Hello World!</html>",
"width": 4,
"height": 6,
"unit": "in",
"test": true,
"encode": true
}
{
"document": "base64 string.......",
"size": "11.29 KB",
"success": true,
"transaction_id": "a5a7cc95-1b9e-45ae-a23d-04baa3ef4e86"
}
This endpoint allows you to create a PDF or PNG from one of our predefined templates. Take a look at the templates before you start. Each template has an example JSON request.
Parameter | Type | Description |
template | string |
A valid template name (
see templates here
). Possible values are:
|
data | object | Data to be passed to the template. See template detail for example requests. All elements within the data object are optional. |
file_type | string | Determines what type of file will be generated. Possible values are pdf or png |
format | string | Paper format. If set, takes priority over width or height options. Valid values are Letter, Legal, Tabloid, Ledger, A0, A1, A2, A3, A4, A5. If the template you are requesting has a fixed size, this parameter is ignored. |
width | number | Document width. If format set, it takes priority over width. If the template you are requesting has a fixed size, this parameter is ignored. |
height | number | Document height. If format set, it takes priority over height. If the template you are requesting has a fixed size, this parameter is ignored. |
unit | string |
Unit of measurement for width and
height. Possible values are:
|
landscape | boolean | Document orientation. |
test | boolean | Create a test document that does not reduce your production credits. Document created will have a "sample" watermark. |
encode | boolean | Return the document as a base64 encoded string. Documents over 4MB cannot be returned as base64. If over 4MB a URL will be returned instead. |
webhook | string | A valid URL where we will send a POST request containing a JSON result. Your webhook should return a 200 status code. |
quality | float | A value between 1 and 3. The higher the value the better the PDF/PNG quality. Please note increasing the document quality makes the resulting file size larger. |
grayscale | boolean | Generates the document in grayscale. |
page_numbers | boolean | Insert page numbers into the footer of each page. Only applies if generated as a PDF. |
name | string | A descriptive name for your document, visible from within the dashboard. |
font | string |
Use a custom font from Google. Browse available fonts:
https://fonts.google.com
. Font name must correspond exactly.
Example values:
|
font_size | number | A numeric value between 0.5 and 1.4. Defines base font size. |
font_color | string | Hex color code. Defines font color. |
s3 | object |
Allows you to save directly to your own Amazon S3 bucket. Requires:
|
object |
Send the generated document as an email attachment or download link.
Maximum attachment size is 9MB. If document exceeds 9MB or you are using your own S3 bucket, a link will be sent in the email body instead. Please note that download links are only valid whilst document remains in storage.
|
# Template Example 1
The following request will create a conference badge as a PNG image. By setting the encode parameter to true, we will receive the resulting document as a base64 string. We have also specified that a custom font be used.
{
"template": "conference_badge",
"file_type" : "png",
"encode": true,
"font" : "Nunito",
"data": {
"logo": "https://docamatic.s3-eu-west-1.amazonaws.com/assets/360_logo.png",
"qr": "10257877877",
"first_name": "Casey",
"last_name": "Williams",
"company": "360 Footwear",
"attendee_type": "Speaker",
"color": "#000000"
}
}
{
"document": "base64 string.......",
"size": "39.25 KB",
"success": true,
"transaction_id": "e40ec4a3-6786-474f-8648-d1d612ddc365"
}
# Template Example 2
The following request will create a shipping label as a PDF and email it as an attachment.
{
"template": "shipping_label_4x3",
"data": {
"logo": "https://docamatic.s3-eu-west-1.amazonaws.com/assets/360_logo.png",
"sender": "360 Footwear, 787 Brunswick, Los Angeles CA 50028",
"recipient": {
"name": "Casey Williams",
"address1": "57 Parkway, 5th Floor",
"address2": "New York",
"address3": "NY 10013"
},
"reference": "1893",
"weight": "1.5KG",
"barcode": "18935949030329293"
},
"email": {
"to": "email-enabled-printer@test.com",
"subject": "Label 1893"
}
}
{
"document": "https://docamatic.s3.eu-west-1.amazonaws.com/prod/34e1e005-e58d-497c-955d-89c0cbbeefde/151a765f-b9xb-4af1-afdd-9863efe289bb.pdf",
"size": "20.65 KB",
"success": true,
"transaction_id": "151a765f-b9xb-4af1-afdd-9863efe289bb"
}
This endpoint allows you to generate an image from a URL or HTML . The source parameter is the only mandatory body parameter. All other parameters are optional. Example requests can be found below this table.
Parameter | Type | Description |
---|---|---|
source | string | A valid URL or HTML. |
media | string | Generate png using screen or print css media. Defaults to screen. Valid values are screen or print. |
width | number | Image width. |
height | number | Image height. |
unit | string |
Unit of measurement for width and
height. Defaults to px. Possible values are:
|
mobile | boolean | Whether the meta viewport tag is taken into account. |
landscape | boolean | Specifies if viewport is in landscape mode. |
full_page | boolean | When true, takes a screenshot of the full scrollable page. |
test | boolean | Create a test image that does not reduce your production credits. Image created will have a "sample" watermark. |
encode | boolean | Return the image as a base64 encoded string. Images over 4MB cannot be returned as base64. If over 4MB a URL will be returned instead. |
webhook | string | A valid URL where we will send a POST request containing a JSON result. Your webhook should return a 200 status code. |
quality | float | A value between 1 and 3. The higher the value the better the image quality. Please note increasing the quality makes the resulting file size larger. |
clip | object |
An object which specifies clipping region of the page. Requires the following fields:
|
grayscale | boolean | Generate the image in grayscale. |
css | string | A valid URL pointing to a CSS file or a valid CSS string. Allows CSS to be injected to the page before the image is generated. Please note if supplying a URL to a CSS asset it must be publicly accessible. |
accept_cookie_warning | boolean | Accept cookie consent notifications prior to generating the image. Unable to target all notifications by default but works for most. See click_elements for manual targeting. |
click_elements | array | Click button or link elements. You can specify which elements to click by specifying the element's CSS class name or the text value of the element. For example, clicking two elements, one by text value and the other by class name: ["Button Text", ".button-class"] |
name | string | A descriptive name for your image. Visible from within the dashboard. |
auth | object |
Allows an image to be created if source URL has been protected behind basic HTTP authentication. Requires:
|
s3 | object |
Allows you to save directly to your own Amazon S3 bucket. Requires:
|
object |
Send the generated document as an email attachment or download link.
Maximum attachment size is 9MB. If document exceeds 9MB or you are using your own S3 bucket, a link will be sent in the email body instead. Please note that download links are only valid whilst document remains in storage.
|
# Image Example 1
The following request will generate an image using a URL passed via the source parameter. We have specified a grayscale , clipped image starting 130px from the top of the viewport, measuring 1440px by 400px. By providing the email parameter, the resulting image will ALSO be sent via email as an attachment.
{
"source": "https://bbc.co.uk",
"grayscale": true,
"clip": {
"x": 0,
"y": 130,
"width": 1440,
"height": 400
},
"email": {
"to": "john.smith@my-company.com",
"subject": "Clipped screenshot"
}
}
{
"document": "https://docamatic.s3.eu-west-1.amazonaws.com/48jKiT339w/11262019/341d581a-e6cf341a364e.png",
"size": "393.52 KB",
"success": true,
"transaction_id": "341d581a-fe8c-425b-9c8c-e6cf341a364e"
}
# Image Example 2
The following example request will create a PNG that fits 4x6 inch dimensions. Raw HTML markup has been passed via the source parameter rather than a URL. The quality parameter has been set to 3 which will result in a higher resolution image. By setting the encode parameter to true, we will receive the resulting document as a base64 string.
{
"source": "<html>Hello World!</html>",
"width": 4,
"height": 6,
"unit": "in",
"quality": 3,
"encode": true
}
{
"document": "base64 string.......",
"size": "27.73 KB",
"success": true,
"transaction_id": "c09e4bd8-0244-4af6-8748-59cc1665f84d"
}
This endpoint allows you to delete a file from storage. Please note that all files are automatically deleted after your defined storage period (set within the dashboard).
# Example Delete Request
The following request will delete a file from storage. The response will advise if deletion was succcessful and the URL of the document deleted.
{
"transaction_id": "8a953f9c-6a97-4453-ba49-092c7f8a28f5"
}
{
"message": "Delete successful",
"url": "https://docamatic.s3.eu-west-1.amazonaws.com/ty372j6F/12042019/8a953f9c-6a97-4453-ba49-092c7f8a28f5.pdf",
"success": true
}
This endpoint provides a summary of your API usage for the current billing period. Assuming a monthly limit of 1000 requests, after 250 production requests:
{
"production": {
"limit": 1000,
"used": 250,
"remaining": 750
},
"test": {
"limit": 1000,
"used": 0,
"remaining": 1000
},
"period_start": "2019-12-30 00:00:00",
"period_end": "2020-01-30 23:59:59"
}