# 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

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

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:

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

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