API

Simple API for painless development

Doxey has been built from developers for developers. We tried our best to create an API that is very simple to use.

Just call the /merge API method and pass the template (either as a sharable link or as a base64 encoded binary) and your data together with some optional parameters and you will get the generated document in return.

/merge

The /merge endpoint supports both GET and POST requests. All optional parameters can be passed either in the request header or as URL parameters.

Parameters

Parameter

Format

Description

template

required

URL

or

base64 encoded document

Pass a sharable link to your template file from Google Drive, OneDrive or Dropbox or a public URL.

model

required

JSON

or

multipart/form-encoded

or

URL-encoded parameters

The data to be merged into the document can be passed as JSON or multipart/form-encoded parameters in the request body when using POST or URL-encoded when using GET requests (see examples below). If the supplied JSON is an array of objects, multiple documents can be generated at once and a zip file containing the documents will be returned.

apiKey

String

Passing your api key will remove the watermark from generated documents and also enables generating Word and LibreOffice documents.

format

pdf
txt

docx

odt
htm

same

Specifies the format of the generated document.

Default format is pdf.

same will return the same format as the template document if possible.

locale

String

Sets the default locale to be used when formatting dates, numbers or currencies.

Locales must be specified using Java Language Tags (e.g. en-US for US English, de-DE for German/Germany)

If not set, the default locale will be en-US.

currency

String

The default currency to be used when rendering currencies.

If not set, the default currency will be USD.

timezone

String

The timezone to be used when formatting dates that do not specify a timezone.

If not set, the default timezone will be GMT.

cache

Number

Sets the time in seconds before reloading the template. Use this parameter to speed up the document generation.

debug

true

false

If debug is set to true Doxey will add error annotations right into the generated document and will also add a stack trace to the error response whenever the server cannot fulfill your request.

content-disposition

download

preview

When invoking the merge in the browser you can specify whether you want download or preview the generated document.

filename

String

Specifies the filename when downloading the document in the browser.

Response

Status code

Format

Description

200

Blob

The /merge method returns the file contents of the generated document.

400

{

  "error" : "error",

  "details" : "xxx",

  "stack" : ""

}

If the document cannot be generated from your template due illegal combination of parameters.

500

{

  "error" : "error",

  "details" : "xxx",

  "stack" : ""

}

If the service encounters an internal error.

GET

The easiest way to run a merge is to append the encoded parameters to the URL. While this approach is limited due to the max length of a URL, it can be handy to generate documents on the fly from a simple link that can be sent via email or chat.

Your data model can either be passed as a URL-parameter in JSON format like this...

URL with encoded model in JSON format

... or you can simply pass each value as a URL parameter:

URL with parameters

You can pass arrays by appending prefixed parameters (starting with <prefix>.) multiple times. The prefix will become the name of the array, the substring after the prefix becomes a property of each object in the array.

URL with array parameter

The following code snippets show how to call the /merge endpoint using a GET request. 

# Replace the url with your own sharable link and add an api key
curl "https://api.doxey.io/merge?template=https%3A%2F%2Fdocs.google.com%2Fdocument%2Fd%2F1q5ghXsjPS8OqjmRH0lDvlUauZ2F5yO_lk1pPAC72zVc%2Fedit&name=World%21" >merged.pdf

<!-- Replace the url with your own sharable link and add an api key -->
<a href="https://api.doxey.io/merge?template=https%3A%2F%2Fdocs.google.com%2Fdocument%2Fd%2F1q5ghXsjPS8OqjmRH0lDvlUauZ2F5yO_lk1pPAC72zVc%2Fedit&name=World!" target="_blank">Create and Download</a>

var response = UrlFetchApp.fetch('https://api.doxey.io/merge?template=https%3A%2F%2Fdocs.google.com%2Fdocument%2Fd%2F1q5ghXsjPS8OqjmRH0lDvlUauZ2F5yO_lk1pPAC72zVc%2Fedit&name=World!');
var blob = response.getBlob();
var code = response.getResponseCode();
Logger.log(code === 200 ? "Success" : "Error Code: " + code);
// sending out email just for demo purposes
GmailApp.sendEmail("[your email goes here to send this to yourself]", "Your generated document", "See attachment",
  { attachments: [{
      fileName: blob.getName(),
      mimeType: "application/pdf",
      content: blob.getBytes()
    }]
  });

// Replace the url with your own sharable link and add an api key
URLConnection conn = new URL("https://api.doxey.io/merge?template=https%3A%2F%2Fdocs.google.com%2Fdocument%2Fd%2F1q5ghXsjPS8OqjmRH0lDvlUauZ2F5yO_lk1pPAC72zVc%2Fedit&name=World%21")
    .openConnection();
conn.setRequestProperty("User-Agent", "Mozilla/5.0 (Windows NT 5.1; rv:19.0) Gecko/20100101 Firefox/19.0");
conn.connect();
InputStream inputStream = conn.getInputStream();
FileOutputStream outputStream = new FileOutputStream(new File("processed.pdf"));
byte[] b = new byte[1024];
int x = 0;
while ((x = inputStream.read(b, 0, 1024)) >= 0) {
  outputStream.write(b, 0, x);
}
outputStream.close();
inputStream.close();

POST

The data model can also be sent in the body of the request in JSON format or form encoded when using a POST request.

Have a look at the HTML example to see how to take advantage of form encoded data, all the other examples use the JSON format. 

# Execute in your shell and the merged document will be saved to a file called merged.pdf
curl https://api.doxey.io/merge \
-X POST \
-H "Content-Type: application/json" \
-d '{ "apiKey": "internal", "template": "https://docs.google.com/document/d/1q5ghXsjPS8OqjmRH0lDvlUauZ2F5yO_lk1pPAC72zVc/edit", "model" : { "name": "World!" } }' \
 >merged.pdf


<form action="https://api.doxey.io/merge" target="_blank">
    <input type="text" name="template" required placeholder="Template URL">
    <input type="text" name="name" required placeholder="Type anything">
    <input type="submit" value="Create and Download">
</form>

function postParameters() {
  var payload = {
    template: "https://docs.google.com/document/d/1q5ghXsjPS8OqjmRH0lDvlUauZ2F5yO_lk1pPAC72zVc/edit",
    model : { name : "World!" }
  };

   var options = {
     contentType: "application/json",
     method : "post",
     payload : Utilities.jsonStringify(payload)
  };

  var response =
    UrlFetchApp.fetch('https://api.doxey.io/merge', options)
  var blob = response.getBlob();
  var code = response.getResponseCode();
  Logger.log(code === 200 ? "Success" : "Error Code: " + code);
}

//
// Checkout and “yarn build” this repo:
// https://github.com/floreysoft/doxey-client-java
//
// Add this dependency to your pom.xml

        <dependency>
            <groupId>com.floreysoft</groupId>
            <artifactId>doxey-client-java</artifactId>
            <version>1.0.13</version>
        </dependency>

//
// Here comes some sample code for using that client
// Please use your apiKey if not testing
//

String apikey = "internal";

ApiClient cl = new ApiClient();
cl.setReadTimeout(1000 * 240);
cl.setBasePath("https://api.doxey.io");
cl.setApiKey(apikey);

DefaultApi api = new DefaultApi(cl);

Map<String, Object> model = new HashMap<>();
model.put("name", "John Doe");

Params p = new Params();
p.setCurrency("EUR");
p.setLocale("de_DE");
p.setTimezone("GMT+01:00");
p.setApiKey(apikey);
p.setFormat(FormatEnum.PDF);
p.setModel(model);
p.setTemplate("https://docs.google.com/document/d/1urL-JV2m85jry1_tatbjSFBjUZgGiMmwwNR9X8UTUTg/edit");

File f = api.mergePost(p);
System.out.println(f.getAbsolutePath());

The pure HTML solution deserves special attention. Doxey has a feature that allows you to pass complex objects and even lists of objects using GET requests. This is especially nice when using links in HTML .

To pass properties of objects you simply use the dot notation for the name of a parameter like in object.property.

If you want a list of objects you pass along as many parameters of the same name as you want. If you pass both object.property=Prop1 and object.property=Prop2 as parameters to a GET request, Doxey will receive a list of objects one having Prop1 as a property, the other Prop2. Have a look at the HTML tab for a complete example. 

<a href="https://api.doxey.io/merge?template=https%3A%2F%2Fdocs.google.com%2Fdocument%2Fd%2F1urL-JV2m85jry1_tatbjSFBjUZgGiMmwwNR9X8UTUTg%2Fedit&name=World&items.name=Project%20Setup&items.description=Create%20github%20repo,%20setup%20timetracker%20and%20Slack%20channels&items.amount=90&items.name=Optimize%20Photos&items.description=Scan,%20crop%20and%20scale%20images%20to%20reduce%20loading%20times&items.amount=340.5&items.name=Website%20structure&items.description=Copy%20blank%20boostrap%20template.%20Setup%20pages%20and%20adjust%20links&items.amount=250.5&items.name=CSS%20theme&items.description=Create%20CSS%20styles%20according%20to%20CI&items.amount=620
" target="_blank">Create and Download</a>

We have prepared a github repository with HTML samples. You can inspect the source and directly try it out: https://github.com/floreysoft/doxey-client-html 

If you’d like to fiddle with a sample Java project (built by Maven and using a client library provided by us), you can have a look at the repository https://github.com/floreysoft/doxey-client-java-sample 

Data types

When passing data you need to know how to format them, so that Doxey can make sense out of them.

Boolean

Booleans can be passed either with or without quotes.

If the value passed is the empty string or false, it is considered to be false. True in all other cases.

Number

Numbers are always specified as fixed point values. If the decimal point actually is . or rather a , depends on the specified locale.

String

Specify them encoded as UTF-8.

Date

Dates are the most complicated values to pass.

The format to be used in JSON is specified in ISO 8601.

If you use this format, you are on the safe side.

As a quick reference, a date formatted according to ISO 8601 might like that 2008-02-01T09:00:22+05:00.

Unfortunately, in some situations you are not free to choose formatting of dates.

These situations include using Google Apps Script or JSON libraries that do the formatting of dates for you.

To help you with that, Doxey tries to accept and parse all standard input formats.

Let us know if there is a format that can not be parsed, but can be considered a standard by any means.

/license

Retrieve information about your license, the number of generated documents in the current month and the number of remaining merges.

Parameters

Parameter

Format

Description

apiKey

String

Pass your api key.

/print

Run a merge and print the generated document on the given printer using the specified tray.

Parameters

Parameter

Format

Description

template

required

URL

or

base64 encoded document

Pass a sharable link to your template file from Google Drive, OneDrive or Dropbox or a public URL.

model

required

JSON

or

multipart/form-encoded

or

URL-encoded parameters

The data to be merged into the document can be passed as JSON or multipart/form-encoded parameters in the request body when using POST or URL-encoded when using GET requests (see examples below).

printer

String

Name of the printer.

Must exactly match the name of the printer as listed in /printers.

tray

String

Name of the paper tray to be use.

Must exactly match the name of the tray as listed in /printers.

apiKey

String

Pass your api key.

locale

String

Sets the default locale to be used when formatting dates, numbers or currencies.

Locales must be specified using Java Language Tags (e.g. en-US for US English, de-DE for German/Germany).

If not set, the default locale will be en-US.

currency

String

The default currency to be used when rendering currencies.

If not set, the default currency will be USD.

timezone

String

The timezone to be used when formatting dates that do not specify a timezone.

If not set, the default timezone will be GMT.

cache

Number

Sets the time in seconds before reloading the template. Use this parameter to speed up the document generation.

/printers

The /printers endpoint will return the available printers and paper trays.

Parameter

Format

Description

apiKey

String

Pass your api key.

Questions and Feedback

If you have any comments on this page, feel free to add suggestions right to the Google document that we are using to create this site.

If you are not yet member of the Doxey community, please join now to get updates from our end or to provide feedback, bug reports and discuss with other users.

Last Updated: 08.01.20