# 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.

Postman screenshot 1

2. Set the headers.

Postman screenshot 2

3. Set the request body and send.

Remember to set "test" to true so that you don't use up your production credits.

Postman screenshot 3

# 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
/pdf 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
POST /pdf
POST https://docamatic.com/api/v1/pdf

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:
  • px pixel
  • in inch
  • cm centimeter
  • mm millimeter
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:
  • px pixel
  • in inch
  • cm centimeter
  • mm millimeter
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_template string HTML template for the print header. Should be valid HTML 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_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:
  • username
  • password
s3 object Allows you to save directly to your own Amazon S3 bucket. Requires:
  • region
  • bucket
  • path (non mandatory)
See Document Storage for example .
email 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.
  • to - a valid email address (mandatory)
  • cc - a valid email address
  • bcc - a valid email address
  • subject - email subject. If nothing supplied default subject "Document created" used
  • body - plain text for the email body
  • filename - attachment filename
See example request below.

# 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.

Request:
    
        {
    "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"
    }
}
    
Response:
    
        {
        "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.

Request:
    
        {
    "source": "<html>Hello World!</html>",
    "width": 4,
    "height": 6,
    "unit": "in",
    "test": true,
    "encode": true
}
    
Response:
    
        {
    "document": "base64 string.......",
    "size": "11.29 KB",
    "success": true,
    "transaction_id": "a5a7cc95-1b9e-45ae-a23d-04baa3ef4e86"
}
    
POST /template
POST https://docamatic.com/api/v1/template

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:
  • invoice1
  • invoice2
  • invoice3
  • invoice4
  • packing_slip
  • returns_form
  • commercial_invoice
  • quotation1
  • quotation2
  • purchase_order
  • table1
  • table2
  • shipping_label_4x6
  • shipping_label_4x3
  • conference_badge
  • visitor_pass
  • barcode_label
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:
  • px pixel
  • in inch
  • cm centimeter
  • mm millimeter
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:
  • Lato
  • Open Sans
  • Nunito
  • Source Sans Pro
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:
  • region
  • bucket
  • path (non mandatory)
See Document Storage for example .
email 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.
  • to - a valid email address (mandatory)
  • cc - a valid email address
  • bcc - a valid email address
  • subject - email subject. If nothing supplied default subject "Document created" used
  • body - plain text for the email body
  • filename - attachment filename
See example request below.

# 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.

Request:
    
        {
    "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"
    }
}
    
Response:
    
        {
    "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.

Request:
    
        {
    "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"
    }
}
    
Response:
    
        {
    "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
POST https://docamatic.com/api/v1/image

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:
  • px pixel
  • in inch
  • cm centimeter
  • mm millimeter
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:
  • 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
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:
  • username
  • password
s3 object Allows you to save directly to your own Amazon S3 bucket. Requires:
  • region
  • bucket
  • path (non mandatory)
See Document Storage for example .
email 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.
  • to - a valid email address (mandatory)
  • cc - a valid email address
  • bcc - a valid email address
  • subject - email subject. If nothing supplied default subject "Document created" used
  • body - plain text for the email body
  • filename - attachment filename
See example request below.

# 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.

Request:
    
        {
    "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"
    }
}
    
Response:
    
        {
        "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.

Request:
    
        {
    "source": "<html>Hello World!</html>",
    "width": 4,
    "height": 6,
    "unit": "in",
    "quality": 3,
    "encode": true
}
    
Response:
    
        {
    "document": "base64 string.......",
    "size": "27.73 KB",
    "success": true,
    "transaction_id": "c09e4bd8-0244-4af6-8748-59cc1665f84d"
}
    
DELETE /delete
DELETE https://docamatic.com/api/v1/delete

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.

Request:
    
        {
    "transaction_id": "8a953f9c-6a97-4453-ba49-092c7f8a28f5"
}
    
Response:
    
        {
    "message": "Delete successful",
    "url": "https://docamatic.s3.eu-west-1.amazonaws.com/ty372j6F/12042019/8a953f9c-6a97-4453-ba49-092c7f8a28f5.pdf",
    "success": true
}
    
GET /credits
GET https://docamatic.com/api/v1/credits

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:

Response:
    
        {
        "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"
    }