# Introduction
The Docamatic API is a RESTful API based on HTTPS requests and JSON responses. If you are registered with Docamatic, you can obtain your API key from the "API Key" page, found here: Go to My account.
The Docamatic API allows you to perform the following tasks:
- Generate PDF documents (convert HTML to PDF)
- Generate documents from templates (JSON to PDF or PNG)
- Generate images/screenshots
- Generate barcodes
- Generate QR codes
# 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 highly recommend it for making test requests and familiarising yourself with the Docamatic API. It’s open source and you can download it for free at https://www.getpostman.com/downloads.
Below are a few screenshots demonstrating how to use postman with the Docamatic API. Check out https://learning.getpostman.com for the 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.
Authentication to the API is performed using the Bearer Token method in the Authorization header.
Authorization: Bearer YOUR_API_KEY
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail with HTTP status code 401.
# 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.
-
200OKRequest successful
-
400Bad RequestRequest was invalid
-
401UnauthorizedUser does not have permission
-
403ForbiddenRequest not authenticated
-
405Method Not AllowedIncorrect HTTP method provided
-
415Unsupported Media TypeResponse is not valid JSON
-
422Unprocessable EntityValid JSON but error encountered
-
429Too many requestsClient is rate limited
-
500Internal Server ErrorServer error, please try again later
# Document Storage
Docamatic gives you full control over how long your documents should be stored. Of course, if your document is returned as a base64 string it will never be stored on our infrastructure.
You can define how long documents should be stored through the "Account Settings" page, found here: 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.
By default, all documents are deleted forever after your desired storage period. You can delete a document at any time using the delete endpoint.
# Endpoints
The 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:
-
POST/pdfGenerate a PDF document from a URL or HTML markup
-
POST/templateGenerate a PDF or PNG from a template
-
POST/imageGenerate an image from a URL or HTML markup
-
POST/barcodeGenerate a barcode
-
POST/qrGenerate a QR code
-
DELETE/deleteDelete a file from storage
-
GET/creditsGet a summary of API usage for the current billing period
POST /pdf
This endpoint allows you to convert HTML to a PDF document from a URL or HTML markup. The source parameter is the only mandatory body parameter. All other parameters are optional. Example requests can be found below this table.
-
sourcestringrequiredA valid URL or HTML markup.
-
mediastringscreenGenerate PDF using screen or print css media. Valid values are screen or print.
-
formatstringLetterPaper format. If set, takes priority over width or height options. Valid values are Letter, Legal, Tabloid, Ledger, A0, A1, A2, A3, A4, A5.
-
margin_topnumbernullTop paper margin.
-
margin_rightnumbernullRight paper margin.
-
margin_bottomnumbernullBottom paper margin.
-
margin_leftnumbernullLeft paper margin.
-
margin_unitstringcmUnit of measurement for margins. Possible values are:
- px pixel
- in inch
- cm centimeter
- mm millimeter
-
widthnumbernullPaper width. If format set, it takes priority over width.
-
heightnumbernullPaper height. If format set, it takes priority over height.
-
unitstringcmUnit of measurement for width and height. Possible values are:
- px pixel
- in inch
- cm centimeter
- mm millimeter
-
landscapebooleanfalsePaper orientation.
-
testbooleanfalseCreate a test document that does not reduce your production credits. Document created will have a "sample" watermark.
-
encodebooleanfalseReturn the document as a base64 encoded string. Documents over 4MB cannot be returned as base64. If over 4MB a URL will be returned instead.
-
webhookstring(URL)nullA valid URL where we will send a POST request containing a JSON result. Your webhook should return a 200 status code.
-
zoomnumber1Scale of the webpage rendering. Defaults to 1. Zoom amount must be between 0.1 and 2.
-
disable_backgroundsbooleanfalseDon't print background graphics.
-
disable_javascriptbooleanfalseWhether or not to disable JavaScript before generating the document.
-
remove_imagesbooleanfalseWhether or not to remove all images before generating the document.
-
grayscalebooleanfalseGenerates the document in grayscale.
-
header_footerbooleanfalseDisplay header and footer.
-
header_templatestring(HTML)nullHTML template for the print header. Should be valid HTML markup with following classes used to inject printing values into them:
- date formatted print date
- title document title
- url document location
- pageNumber current page number
- totalPages total pages in the document
-
footer_templatestring(HTML)nullHTML template for the print footer. Should use the same format as the header_template
-
page_numbersbooleanfalseInsert page numbers into the footer of each page. Ignored if footer_template has been set.
-
cssstring(URL or CSS)nullA 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_sizebooleanfalseGive 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_rangesstringnullPaper ranges to print, e.g., '1-5, 8, 11-13'. Defaults to the empty string, which means print all pages.
-
accept_cookie_warningbooleantrueAccept 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_elementsarraynullClick 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"]
-
namestringDocumentA descriptive name for your document. Visible from within the dashboard and when calling the /documents endpoint.
-
authobjectnullAllows a document to be created if source URL has been protected behind basic HTTP authentication. Requires:
- username
- password
-
email.to
Indicates an array (see example request below)string(email)nullSend the generated document as an email attachment or download link. Maximum attachment size is 9MB. If document exceeds 9MB a link will be sent in the email body instead. Please note that download links are only valid whilst document remains in storage. Sending via email is only supported on paid plans. -
email.ccstring(email)nullA single carbon copy recipient. Only valid if to address supplied.
-
email.bccstring(email)nullA single blind carbon copy recipient. Only valid if to address supplied.
-
email.subjectstringnullEmail subject. If nothing supplied default subject "Document created" used.
-
email.bodystringnullPlain text for the email body.
# PDF Example Request 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"
}
}
# PDF Example Response 1
{
"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 Request 2
The following example request will create a 4x6 inch PDF test document using HTML markup 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
}
# PDF Example Response 2
{
"document": "base64 string.......",
"size": "11.29 KB",
"success": true,
"transaction_id": "a5a7cc95-1b9e-45ae-a23d-04baa3ef4e86"
}
POST /template
This endpoint allows you to create a PDF or PNG document from a template. Before you begin, please take a look here to see templates available. Below each template you can find an example JSON request.
-
templatestringrequiredA valid template name. See templates page here for templates available. Possible values are:
- invoice1
- invoice2
- invoice3
- packing_slip
- returns_form
- commercial_invoice
- quotation1
- quotation2
- purchase_invoice
- table1
- table2
- shipping_label_4x6
- shipping_label_4x3
- conference_badge
-
dataobjectrequiredData to be passed to the template. See templates page here for example requests. All elements within the data object are optional.
-
file_typestringpdfDetermines what type of file will be generated. Possible values are pdf or png.
-
formatstringLetterPaper 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.
-
widthnumbernullPaper width. If format set, it takes priority over width. If the template you are requesting has a fixed size, this parameter is ignored.
-
heightnumbernullPaper height. If format set, it takes priority over height. If the template you are requesting has a fixed size, this parameter is ignored.
-
unitstringcmUnit of measurement for width and height. Possible values are:
- px pixel
- in inch
- cm centimeter
- mm millimeter
-
landscapebooleanfalsePaper orientation.
-
testbooleanfalseCreate a test document that does not reduce your production credits. Document created will have a "sample" watermark.
-
encodebooleanfalseReturn the document as a base64 encoded string. Documents over 4MB cannot be returned as base64. If over 4MB a URL will be returned instead.
-
webhookstring(URL)nullA valid URL where we will send a POST request containing a JSON result. Your webhook should return a 200 status code.
-
qualityfloat1A 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.
-
grayscalebooleanfalseGenerates the document in grayscale.
-
page_numbersbooleanfalseInsert page numbers into the footer of each page. Only applies if generated as a PDF.
-
namestringDocumentA descriptive name for your document. Visible from within the dashboard and when calling the /documents endpoint.
-
fontstringRobotoUse a custom font from Google. Browse available fonts: https://fonts.google.com. Font name must correspond exactly. Example values:
- Lato
- Open Sans
- Nunito
- Source Sans Pro
-
font_sizenumber0.8A numeric value between 0.7 and 1.4. Defines base font size.
-
font_colorstring#000000Hex color code. Defines font color.
-
email.to
Indicates an array (see example request below)string(email)nullSend the generated document as an email attachment or download link. Maximum attachment size is 9MB. If document exceeds 9MB a link will be sent in the email body instead. Please note that download links are only valid whilst document remains in storage. Sending via email is only supported on paid plans. -
email.ccstring(email)nullA single carbon copy recipient. Only valid if to address supplied.
-
email.bccstring(email)nullA single blind carbon copy recipient. Only valid if to address supplied.
-
email.subjectstringnullEmail subject. If nothing supplied default subject "Document created" used.
-
email.bodystringnullPlain text for the email body.
# Template Example Request 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"
}
}
# Template Example Response 1
{
"document": "base64 string.......",
"size": "39.25 KB",
"success": true,
"transaction_id": "e40ec4a3-6786-474f-8648-d1d612ddc365"
}
# Template Example Request 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",
"from": "360 Footwear, 787 Brunswick, Los Angeles CA 50028",
"to": {
"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"
}
}
# Template Example Response 2
{
"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"
}
POST /image
This endpoint allows you to generate an image from a URL or HTML markup . The source parameter is the only mandatory body parameter. All other parameters are optional. Example requests can be found below this table.
-
sourcestringrequiredA valid URL or HTML markup.
-
mediastringscreenGenerate png using screen or print css media. Defaults to screen. Valid values are screen or print.
-
widthnumber1440Page width.
-
heightnumber900Page height.
-
unitstringpxUnit of measurement for width and height. Defaults to px. Possible values are:
- px pixel
- in inch
- cm centimeter
- mm millimeter
-
mobilebooleanfalseWhether the meta viewport tag is taken into account.
-
landscapebooleanfalseSpecifies if viewport is in landscape mode.
-
full_pagebooleanfalseWhen true, takes a screenshot of the full scrollable page.
-
testbooleanfalseCreate a test document that does not reduce your production credits. Document created will have a "sample" watermark.
-
encodebooleanfalseReturn the document as a base64 encoded string. Documents over 4MB cannot be returned as base64. If over 4MB a URL will be returned instead.
-
webhookstring(URL)nullA valid URL where we will send a POST request containing a JSON result. Your webhook should return a 200 status code.
-
qualityfloat1A value between 1 and 3. The higher the value the better the PNG quality. Please note increasing the quality makes the resulting file size larger.
-
clipobjectnullAn object which specifies clipping region of the page. Requires the following fields:
- x x-coordinate of top-left corner of clip area
- y y-coordinate of top-left corner of clip area
- width width of clipping area
- height height of clipping area
-
disable_backgroundsbooleanfalseDon't print background graphics.
-
disable_javascriptbooleanfalseWhether or not to disable JavaScript before generating the document.
-
grayscalebooleanfalseGenerate the image in grayscale.
-
cssstring(URL or CSS)nullA 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.
-
accept_cookie_warningbooleantrueAccept 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_elementsarraynullClick 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"]
-
namestringDocumentA descriptive name for your document. Visible from within the dashboard and when calling the /documents endpoint.
-
authobjectnullAllows a document to be created if source URL has been protected behind basic HTTP authentication. Requires:
- username
- password
-
email.to
Indicates an array (see example request below)string(email)nullSend the generated document as an email attachment or download link. Maximum attachment size is 9MB. If document exceeds 9MB a link will be sent in the email body instead. Please note that download links are only valid whilst document remains in storage. Sending via email is only supported on paid plans. -
email.ccstring(email)nullA single carbon copy recipient. Only valid if to address supplied.
-
email.bccstring(email)nullA single blind carbon copy recipient. Only valid if to address supplied.
-
email.subjectstringnullEmail subject. If nothing supplied default subject "Document created" used.
-
email.bodystringnullPlain text for the email body.
# Image Example Request 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"
}
}
# Image Example Response 1
{
"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 Request 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
}
# Image Example Response 2
{
"document": "base64 string.......",
"size": "27.73 KB",
"success": true,
"transaction_id": "c09e4bd8-0244-4af6-8748-59cc1665f84d"
}
POST /barcode
This endpoint allows you to create a barcode as a PNG image.
-
datastringrequiredData to be represented as a barcode.
-
barcode_typestringCODE_128Determines what type of barcode that will be generated. Defaults to CODE_128. Possible values are:
- CODE_39
- CODE_39_CHECKSUM
- CODE_39E
- CODE_39E_CHECKSUM
- CODE_93
- STANDARD_2_5
- STANDARD_2_5_CHECKSUM
- INTERLEAVED_2_5
- INTERLEAVED_2_5_CHECKSUM
- CODE_128
- CODE_128_A
- CODE_128_B
- CODE_128_C
- EAN_2
- EAN_5
- EAN_8
- EAN_13
- UPC_A
- UPC_E
- MSI
- MSI_CHECKSUM
- POSTNET
- PLANET
- RMS4CC
- KIX
- IMB
- CODABAR
- CODE_11
- PHARMA_CODE
- PHARMA_CODE_TWO_TRACKS
-
widthnumber2Width of a single bar element in pixels.
-
heightnumber80Height of a single bar element in pixels.
-
testbooleanfalseCreate a test barcode that does not reduce your production credits. Barcode created will have a "sample" watermark.
-
encodebooleanfalseReturn the barcode as a base64 encoded string.
-
webhookstring(URL)nullA valid URL where we will send a POST request containing a JSON result. Your webhook should return a 200 status code.
# Example Barcode Request
The following request will create a PNG barcode. We have requested a CODE_39 barcode type and specified the size of the barcode. Please remember that the width refers to the width of a single bar element in pixels.
{
"data": "800453945349593130029",
"barcode_type": "CODE_39",
"width": 1,
"height": 40
}
# Example Barcode Response
{
"document": "https://docamatic-dev.s3.eu-west-1.amazonaws.com/y5t4fwaQ/12042019/2fca86a4-7e9e-4460-b3be-8f2e5ec8ed6f.png",
"size": "149 B",
"success": true,
"transaction_id": "2fca86a4-7e9e-4460-b3be-8f2e5ec8ed6f"
}
POST /qr
This endpoint allows you to create a QR code as a PNG image.
-
datastringrequiredData to be represented as a QR.
-
sizenumber100QR size in pixels.
-
marginnumber0Margin around the QR in pixels.
-
testbooleanfalseCreate a test QR code that does not reduce your production credits. QR created will have a watermark.
-
encodebooleanfalseReturn the QR as a base64 encoded string.
-
webhookstring(URL)nullA valid URL where we will send a POST request containing a JSON result. Your webhook should return a 200 status code.
# Example QR Request
The following request will create a QR code as a PNG image. The QR code generated will contain a URL pointing to google.com. The QR code dimensions will be 75px by 75px, with a 5px margin.
{
"data": "https://www.google.com",
"size": 75,
"margin": 5
}
# Example QR Response
{
"document": "https://docamatic.s3.eu-west-1.amazonaws.com/WjkPvu1/12302019/ca677eb0-0019-4829-9e65-fa2097d40a49.png",
"size": "761 B",
"success": true,
"transaction_id": "ca677eb0-0019-4829-9e65-fa2097d40a49"
}
DELETE /delete
This endpoint allows you to delete a file from storage. Please note that all files are automatically deleted after 48 hours.
-
transaction_idstring(uuid)requiredA valid transaction_id returned from the original call to generate the file.
# Example Delete Request
The following request will delete a file from storage.
{
"transaction_id": "8a953f9c-6a97-4453-ba49-092c7f8a28f5"
}
# Example Delete Response
The response will advise if the corresponding file was deleted successfully. The URL of the file that was deleted will also be returned.
{
"message": "Delete successful",
"url": "https://docamatic.s3.eu-west-1.amazonaws.com/ty372j6F/12042019/8a953f9c-6a97-4453-ba49-092c7f8a28f5.pdf",
"success": true
}
GET /credits
This endpoint provides a summary of your API usage for the current billing period.
# Example Credits Response
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"
}