API Reference
LabraDocs comes with two API endpoints for converting docx documents to PDF/UA. The first endpoint should be used if you prefer specifying the input data in separate files, the second endpoint should be used if you prefer to specify the input data in a single JSON file.
/docx2pdfua and /docx2docx
/docx2docx only available from v1.6.0
Request
- Conversion with separate input files
- Method:
POST - Input:
template- the docx file to be converted (required)data- a JSON file containing the data to be inserted into the template (optional)images- an optional array of images to be inserted into the template (optional)
- Response:
application/pdf - Return codes:
200- conversion successful400- bad request500- internal server error
- cURL
- C#
- node
curl --location --request POST 'http://localhost:8000/docx2pdfua' \
--form 'template=@"/home/pathfindr/example/generic.docx"' \
--form 'data=@"/home/pathfindr/example/generic.json"' \
--form 'images=@"/home/pathfindr/example/logo.png"' \
--form 'images=@"/home/pathfindr/example/another-image.png"'
var client = new RestClient("http://localhost:8000/docx2pdfua");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddFile("template", "/home/pathfindr/example/generic.docx");
request.AddFile("data", "/home/pathfindr/example/generic.json");
request.AddFile("images", "/home/pathfindr/example/logo.png");
request.AddFile("images", "/home/pathfindr/example/another-image.png");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
var request = require('request');
var fs = require('fs');
var options = {
'method': 'POST',
'url': 'http://localhost:8000/docx2pdfua',
'headers': {
},
formData: {
'template': {
'value': fs.createReadStream('/home/pathfindr/example/generic.docx'),
'options': {
'filename': 'generic.docx',
'contentType': null
}
},
'data': {
'value': fs.createReadStream('/home/pathfindr/example/generic.json'),
'options': {
'filename': 'generic.json',
'contentType': null
}
},
'images': {
'value': fs.createReadStream('/home/pathfindr/example/logo.png'),
'options': {
'filename': 'logo.png',
'contentType': null
}
},
'images': {
'value': fs.createReadStream('/home/pathfindr/example/another-image.png'),
'options': {
'filename': 'another-image',
'contentType': null
}
}
}
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
Adding /extract_mergefields to the end of the endpoints will return a list of all the mergefields in the template
You may download the demo files here: generic.docx, generic.json and the logo.png files here.
JSON file format
In the JSON file you have to specify the data and image mappings. For the data you may use nesting such as arrays and objects. To reference data structures in the docx file, you have to use "." to separate the different nesting levels.
See the following example for easier understanding
{
"CUSTOMERNAME": "Jens Jensen", // can be referenced as «CUSTOMERNAME»
"CUSTOMERADDRESS": "...", // can be referenced as «CUSTOMERADDRESS»
"CUSTOMER": {
"NAME": "Jens Jensen", // can be referenced as «CUSTOMER.NAME»
"ADDRESS": "..." // can be referenced as «CUSTOMER.ADDRESS»
},
"LOGO": { // the name of the IMAGE, which is used in the docx document to reference the image
"src": "logo.png", // the name of the file submitted in the images array
"title": "Logo", // title for screenreaders
"alt": "Logo" // alt text for screenreaders
},
"ANOTHERIMAGE": {
"src": "another-image.png",
"title": "Another image",
"alt": "Another image"
}
}
All names are case sensitivie, so make sure to use the same case in the docx document and in the JSON file.
/docx2pdfua_packed and /docx2docx_packed
/docx2docx_packed only available from v1.6.0
Request
- Conversion with a single input file
- Method:
POST - Input: all files packed together into one JSON file
- Response:
application/pdf - Return codes:
-
200- conversion successful -
400- bad request -
500- internal server error
-
- cURL
- C#
- node
curl --location --request POST 'http://localhost:8000/docx2pdfua_packed' \
--header 'Content-Type: application/json' \
--data-binary '@/home/pathfindr/dev/docx2pdfua/example/generic.packed.json'
var client = new RestClient("http://localhost:8000/docx2pdfua_packed");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "<file contents here>", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
var http = require('follow-redirects').http;
var fs = require('fs');
var options = {
'method': 'POST',
'hostname': 'localhost',
'port': 8000,
'path': '/docx2pdfua_packed',
'headers': {
'Content-Type': 'application/json'
},
'maxRedirects': 20
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function (chunk) {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
res.on("error", function (error) {
console.error(error);
});
});
var postData = "<file contents here>";
req.write(postData);
req.end();
Adding /extract_mergefields to the end of endpoints will return a list of all the mergefields in the template
You may download the demo file here: generic.packed.json
JSON file format
When using a single file, the JSON file should contain all the images templates and data that has to be merged together before converting it to a PDF/UA file.
The JSON file contains the following fields:
template: json object with the property "templateBase64": containing the base64 encoded word documentdata: json object with arrays, objects, strings, numbers and booleansimages: array of json objects containing the "name" (string) to be replaced, the base 64 encoded image in the "base64" property, the "title" and the "alt" text for the image itself
In this setup all three fields are required.
See the example below
{
"template": { templateBase64: "base64 encoded word document" },
"data": {
"CUSTOMERNAME": "Jens Jensen", // can be referenced as «CUSTOMERNAME»
"CUSTOMERADDRESS": "...", // can be referenced as «CUSTOMERADDRESS»
"CUSTOMER": {
"NAME": "Jens Jensen", // can be referenced as «CUSTOMER.NAME»
"ADDRESS": "..." // can be referenced as «CUSTOMER.ADDRESS»
},
"ITEMS: [ // can be referenced in loops
{
"NAME": "Item 1",
"PRICE": 10
},
{
"NAME": "Item 2",
"PRICE": 20
}
]
},
"images": [
{
"name": "LOGO", // the name of the IMAGE, which is used in the docx document to reference the image
"base64": "base64 encoded image", // the base64 encoded image
"title": "Logo", // title for screenreaders
"alt": "Logo" // alt text for screenreaders
},
{
"name": "ANOTHERIMAGE",
"base64": "base64 encoded image",
"title": "Another image",
"alt": "Another image"
}
]
}
You may download the demo file here: generic.packed.json
If you want to learn more about how to use mergefields, please continue start out at the beginning.
/pdf_fill
available from v1.7.0
Request
- Filling in PDF forms with separate input files
- Method:
POST - Input:
template- the docx file to be converted (required)data- a JSON file containing the data to be inserted into the template (optional)
- Response:
application/pdf - Return codes:
200- conversion successful400- bad request500- internal server error
- cURL
- C#
- node
curl --location --request POST 'http://localhost:8000/pdf_fill' \
--form 'template=@"/home/pathfindr/example/generic.pdf"' \
--form 'data=@"/home/pathfindr/example/generic.json"' \
var client = new RestClient("http://localhost:8000/pdf_fill");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddFile("template", "/home/pathfindr/example/generic.pdf");
request.AddFile("data", "/home/pathfindr/example/generic.json");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
var request = require('request');
var fs = require('fs');
var options = {
'method': 'POST',
'url': 'http://localhost:8000/pdf_fill',
'headers': {
},
formData: {
'template': {
'value': fs.createReadStream('/home/pathfindr/example/generic.pdf'),
'options': {
'filename': 'generic.pdf',
'contentType': null
}
},
'data': {
'value': fs.createReadStream('/home/pathfindr/example/generic.json'),
'options': {
'filename': 'generic.json',
'contentType': null
}
},
}
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
JSON file format
In the JSON file you have to specify the data mappings. For the data you may use nesting such as arrays and objects. See the following example for easier understanding
{
"CUSTOMER NAME": "Jens Jensen", // can be referenced as «CUSTOMER NAME»
"CUSTOMER ADDRESS": "...", // can be referenced as «CUSTOMER ADDRESS»
}
Adding /extract_mergefields to the end of endpoints will return a list of all the mergefields in the template
Data fields support spaces, but no nested data is allowed. Keys like "person.cpr" or "person.address" will only work if the data key actually contains a "." character and will not work if it's an object, so this is invalid:
{"person": {"address": "some address", "cpr": "123456-1234"}}.
All names are case sensitivie, so make sure to use the same case in the docx document and in the JSON file.
/pdf_fill_packed
available from v1.7.0
Request
- Filling in PDF forms with a single input file
- Method:
POST - Input: all files packed together into one JSON file
- Response:
application/pdf - Return codes:
-
200- conversion successful -
400- bad request -
500- internal server error
-
- cURL
- C#
- node
curl --location --request POST 'http://localhost:8000/pdf_fill_packed' \
--header 'Content-Type: application/json' \
--data-binary '@/home/pathfindr/dev/docx2pdfua/example/generic.packed.json'
var client = new RestClient("http://localhost:8000/pdf_fill_packed");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "<file contents here>", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
var http = require('follow-redirects').http;
var fs = require('fs');
var options = {
'method': 'POST',
'hostname': 'localhost',
'port': 8000,
'path': '/pdf_fill_packed',
'headers': {
'Content-Type': 'application/json'
},
'maxRedirects': 20
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function (chunk) {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
res.on("error", function (error) {
console.error(error);
});
});
var postData = "<file contents here>";
req.write(postData);
req.end();
Adding /extract_mergefields to the end of endpoints will return a list of all the mergefields in the template
JSON file format
When using a single file, the JSON file should contain all the images templates and data that has to be merged together before converting it to a PDF/UA file.
The JSON file contains the following fields:
template: json object with the property "templateBase64": containing the base64 encoded word documentdata: json object with arrays, objects, strings, numbers and booleans
In this setup both fields are required.
See the example below
{
"template": { templateBase64: "base64 encoded word document" },
"data": {
"CUSTOMER NAME": "Jens Jensen", // can be referenced as «CUSTOMER NAME»
"CUSTOMER ADDRESS": "...", // can be referenced as «CUSTOMER ADDRESS»
}
}
Data fields support spaces, but no nested data is allowed. Keys like "person.cpr" or "person.address" will only work if the data key actually contains a "." character and will not work if it's an object, so this is invalid:
{"person": {"address": "some address", "cpr": "123456-1234"}}.
All names are case sensitivie, so make sure to use the same case in the docx document and in the JSON file.
If you want to learn more about how to use mergefields, please continue start out at the beginning.