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

• Convert HTML to PDF
• Generate documents from templates
• Capture 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
• Ruby
• Python
• PHP
• Node.js

    
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);
    

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

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

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

# Template Example Request

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.

    
{
    "template": "conference_badge",
    "encode": true,
    "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

    
{
    "document": "base64 string.......",
    "size": "39.25 KB",
    "success": true,
    "transaction_id": "e40ec4a3-6786-474f-8648-d1d612ddc365"
}
    

POST /screenshot

This endpoint allows you to capture a screenshot 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.

# Screenshot Example Request 1

The following request will capture a screenshot using a URL passed via the source parameter. We have specified a grayscale, clipped screenshot starting 130px from the top of the viewport, measuring 1440px by 400px. By providing the email parameter, the resulting screenshot 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"
    }
}
    

# Screenshot 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"
    }
    

# Screenshot 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
}
    

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

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

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

# 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"
}