# Introduction

The Docamatic API is a RESTful API based on HTTPS requests and JSON responses. The API provides 5 main endpoints:

• HTML to PDF API - for generating PDF documents from a URL or HTML.
• Template API - for generating PDFs or images from JSON.
• Image/Screenshot API - for generating images from a URL or HTML.
• Write to PDF API - for adding text, images, QR codes and barcodes to an existing PDF.
• Encrypt PDF API - for password protecting an existing PDF.

You can create PDFs and images with no code by using our Zapier integration .

# 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

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.

# 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, documents are automatically 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.

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

# Zapier Integration

Docamatic's integration with Zapier allows you to easily connect with thousands of other apps. The integration allows you to auto generate PDFs and images, then perform custom workflows on the documents generated: Setup Zapier Here

# Webhooks

If you specify the webhook parameter within your API request, we will send a POST request to your webhook endpoint when the document has been generated. The JSON posted to your endpoint will contain a URL to the generated document.

Example request:

    
        {
    "source": "<html>Report...</html>",
    "webhook": "https://my-site.com/webhook",
}
    

Example response:

    
        {
    "document": "https://docamatic.s3.eu-west-1.amazonaws.com/prod/34e1e099-e58d-887c-955d-82c0cbbeefde/464f5c96-174b-4a24-a1d5-fc84a2861fxr.pdf",
    "transaction_id": "464f5c96-174b-4a24-a1d5-fc84a2861fxr"
}
    

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

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.

# 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 image from one of our predefined templates. Take a look at the templates before you start. Each template has an example JSON request.

# 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 or screenshot. The source parameter is the only mandatory body parameter. All other parameters are optional. Example requests can be found below this table.

# 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 add text, images, barcodes and QR codes to an existing pdf document. Example requests can be found below this table.

Also, be sure to check out these short guides: Add text, images and barcodes to a PDF with a single API request and Stamp PDFs with an API Request .

# Write to PDF Example 1

The following request will add text, an image, a barcode and a QR code to an existing PDF document. The existing PDF to be written to has been passed via the source parameter as a URL. Text will be written to the PDF using default font family Arial in the default color black. A custom font size of 24 has been supplied. The x and y parameters are used to position the text on the page. As the page_number parameter has not been passed, the text will be added to all of the pages on the PDF. The page_number parameter has been specified for barcode and QR code, meaning they will only be displayed on page 2. By providing the email parameter, the resulting document will ALSO be sent via email as an attachment.

    
        {
        "source": "https://docamatic.s3.eu-west-1.amazonaws.com/assets/write-to-pdf-demo.pdf",
        "text": [
            {
                "text_value": "Hello world!",
                "font_size": 24,
                "text_x": 18,
                "text_y": 100
            }
        ],
        "cells": [
            {
                "height": 8,
                "align": "C",
                "text_value": "This is cell Line 1\nThis is cell Line 2",
                "text_color": "#CC0000",
                "cell_x": 0,
                "cell_y": 110
            }
        ],
        "images": [
            {
                "image_url": "https://docamatic.com/apple-touch-icon.png",
                "image_width": 20,
                "image_height": 20,
                "image_x": 18,
                "image_y": 140
            }
        ],
        "barcodes": [
            {
                "barcode_value": "90337210573",
                "barcode_width": 64,
                "barcode_height": 20,
                "barcode_x": 60,
                "barcode_y": 140,
                "barcode_page_number": 2
            }
        ],
        "qr_codes": [
            {
                "qr_code_value": "https://google.com",
                "qr_code_size": 20,
                "qr_code_x": 160,
                "qr_code_y": 140,
                "qr_code_page_number": 2
            }
        ],
        "email": {
            "to": "john.smith@my-company.com",
            "subject": "PDF attached"
        }
    }
    

    
        {
    "document": "https://docamatic.s3.eu-west-1.amazonaws.com/prod/34e1e005-e58d-497c-955d-89c0cbbeefde/151a765f-b9xb-4af1-afdd-9863efe289bb.pdf",
    "size": "30.95 KB",
    "success": true,
    "transaction_id": "851f765f-b9xb-4af1-af11-9863efe28922"
}
    

# Write to PDF Example 2

The following example request will add two text strings to an existing PDF document. The existing PDF to be written to has been passed via the source parameter as base64 encoded PDF string. The first text element added to the PDF will be writted using a custom color and font family "Courier". The text style has been defined (B)old, (U)nderline, (I)talic. By specifying the page_number parameter, the first text element will only be written to the first page of the PDF. By setting the encode parameter to true, we will receive the resulting document as a base64 string.

    
        {
    "source": "base64 encoded PDF.......",
    "text": [
        {
            "text_value": "I love PDFs :D",
            "text_color": "#FF0000",
            "font": "courier",
            "font_size": 16,
            "font_style": "BUI",
            "text_x": 120,
            "text_y": 80,
            "text_page_number": 1
        },
        {
            "text_value": "PDFs rock",
            "text_x": 120,
            "text_y": 85
        },
    ],
    "encode": true
}
    

    
        {
    "document": "base64 string.......",
    "size": "128.28 KB",
    "success": true,
    "transaction_id": "x09e4bd8-0243-4af6-8748-79cc16659f89"
}
    

This endpoint allows you to password protect an existing pdf document. Example requests can be found below this table.

# Encrypt PDF Example 1

The following example request will password protect an existing PDF document using the default 256bit AES encryption.

    
        {
    "source": "https://example.com/example.pdf",
    "password": "pw123#"
}
    

    
        {
    "document": "https://docamatic.s3.eu-west-1.amazonaws.com/48jKiT339w/11262019/941d581a-e6cf341a3647.pdf",
    "size": "77.73 KB",
    "success": true,
    "transaction_id": "941d581a-fe8c-425b-9c8c-e6cf341a3647"
}
    

# Encrypt PDF Example 2

The following example request will password protect an existing PDF document using 128bit AES encryption. The PDF to be password protected has been passed via the source parameter as base64 encoded PDF string. By setting the encode parameter to true, we will receive the resulting document as a base64 string.

    
        {
    "source": "base64 encoded PDF.......",
    "password": "pw123#",
    "encryption": "AES_128",
    "encode": true
}
    

    
        {
    "document": "base64 string.......",
    "size": "77.73 KB",
    "success": true,
    "transaction_id": "by9e4bd8-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"
    }