Introduction

The PDF Generation API features a RESTful architecture, allowing you to code in the language of your choice. This API supports the JSON media type, and uses UTF-8 character encoding.

Getting started

First thing is to create your FREE SANDBOX ACCOUNT, its free for testing and integration process. Once you are ready to go live just upgrade to one of the monthly plans that fits to your needs. If you need a custom quote then please contact us info@actualreports.com.

Example templates

Here is a list of public templates that you can use for testing the output generation.

ID Name Data
21661 Packing Slip Example JSON
21650 Invoice Blue Example JSON
21649 Invoice Blue Example 2 JSON
21648 Invoice Green Example JSON

Definitions

Organization

Organization is a group of workspaces owned by your account.

Workspace

Workspace contains templates. Each workspace has access to their own templates and organization default templates.

Master Workspace

Master Workspace is the main/default workspace of your Organization. The Master Workspace identifier is the email you signed up with.

Default Template

Default template is a template that is available for all workspaces by default. You can set the template access type under Page Setup. If template has "Organization" access then your users can use them from the "New" menu in the Editor.

Access types
Private - template is visible only in workspace where it was created
Organization - template is visible on all workspaces

Data Field

Data Field is a placeholder for the specific data in your JSON data set. In this example JSON you can access the buyer name using Data Field {paymentDetails::buyerName}. The separator between depth levels is :: (two colons). When designing the template you don’t have to know every Data Field, our editor automatically extracts all the available fields from your data set and provides an easy way to insert them into the template.

        
{
    "documentNumber": 1,
    "paymentDetails": {
        "method": "Credit Card",
        "buyerName": "John Smith"
    },
    "items": [
        {
            "id": 1,
            "name": "Item one"
        }
    ]
}
        
      

Authentication

The Base URI is https://pdfgeneratorapi.com/api/v3

To authenticate, you’ll need to use your app key and secret, sent along with the following headers. You need to generate a new signature value for each API request.
X-Auth-Key: {key}
X-Auth-Workspace: {workspace}
X-Auth-Signature: {signature}
Content-Type: application/json; charset=utf-8
Accept: application/json

As an alternative you can send key, workspace and signature values as query parameters. This is useful for redirecting user to editor without a form submit.
https://pdfgeneratorapi.com/api/v3/template/123456/editor?key={key}&workspace={workspace}&signature={signature}

Creating signature

{signature} = HMAC-SHA256({key}{resource}{workspace}, {secret})

Where
{key} is your API key found under your Account Settings
{secret} is your API secret found under your Account Settings
{resource} is the API request resource e.g templates/123456/output
{workspace} is an unique string created by your application that identifies the workspace.
{signature} is HMAC SHA256 hash

Before creating the signature you need to sort the values alphabetically by the param name (or key if using array).


  $key = 'abcdefghijk';
  $secret = 'abcdefghijkabcdefghijk';
  $workspace = '123456@myawesomeapp.com';
  $resource = 'templates/123456/output';
  $documentData = json_encode([
    'documentNumber' => 1,
    'buyer' => ['name' => 'John Smith', 'email' => 'john@smith.com']
  ]);

  $data = [
    'key' => $key,
    'resource' => $resource,
    'workspace' => $workspace
  ];
  ksort($data);

  $signature = hash_hmac('sha256', implode('', $data), $secret);


  /**
   * Authentication params sent with headers
   */
  curl -H "X-Auth-Key: $key" \
    -H "X-Auth-Workspace: $workspace" \
    -H "X-Auth-Signature: $signature" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -X POST -d "$documentData" https://pdfgeneratorapi.com/api/v3/templates/123456/output

  /**
   * Authentication params sent in query string
   */
  curl -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -X POST -d "$documentData" https://pdfgeneratorapi.com/api/v3/templates/123456/output?key=$key&workspace=$workspace&signature=$signature


  /**
   * Authentication params sent with headers
   */
  $client = new \GuzzleHttp\Client([
      'base_uri' => 'https://pdfgeneratorapi.com/api/v3/'
  ]);

  $response = $client->request('POST', $resource, [
    'body' => $documentData,
    'headers' => [
      'X-Auth-Key' => $key,
      'X-Auth-Workspace' => $workspace,
      'X-Auth-Signature' => $signature,
      'Accept' => 'application/json',
      'Content-Type' => 'application/json; charset=utf-8',
    ]
  ]);

  /**
   * Authentication params sent in query string
   */
  $client = new \GuzzleHttp\Client([
      'base_uri' => 'https://pdfgeneratorapi.com/api/v3/'
  ]);

  $response = $client->request('POST', $resource, [
    'body' => $documentData,
    'query' => [
      'key' => $key,
      'workspace' => $workspace,
      'signature' => $signature
    ]
  ]);

API reference

The Base URI is https://pdfgeneratorapi.com/api/v3

Each API request has to include key, workspace and signature values in headers or in query params. For more information please see the Authentication section.

Get templates

GET https://pdfgeneratorapi.com/api/v3/templates

Returns list of templates in the workspace.

Request parameters

access:
string Allows to filter templates by access type. Comma separated list of access types.
Available access types: organization, private
tags:
string Allows to filter templates by assigned tags. Comma separated list of tags assigned to template.

Response attributes

response:
array Array of templates

Template object

id:
integer Template unique id
name:
string Template name
modified:
string Datetime of last modification
owner:
boolean true access type: private
false access type: organization
tags:
array Tags assigned to template

  curl -H "X-Auth-Key: $key" \
    -H "X-Auth-Workspace: $workspace" \
    -H "X-Auth-Signature: $signature" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -X GET https://pdfgeneratorapi.com/api/v3/templates


  $client = new \GuzzleHttp\Client([
      'base_uri' => 'https://pdfgeneratorapi.com/api/v3/',
  ]);

  $response = $client->request('GET', 'templates', [
    'headers' => [
      'X-Auth-Key' => $key,
      'X-Auth-Workspace' => $workspace,
      'X-Auth-Signature' => $signature
      'Accept' => 'application/json',
      'Content-Type' => 'application/json; charset=utf-8'
    ]
  ]);


{
  "response": [
    {
      "id": 24382,
      "name": "Invoice template",
      "modified": "2017-10-30 16:49:28",
      "owner": true,
      "tags": [
        "order",
        "invoice"
      ]
    },
    {
      "id": 24381,
      "name": "Label template",
      "modified": "2017-10-21 11:49:28",
      "owner": false,
      "tags": []
    }
  ]
}

Get template

GET https://pdfgeneratorapi.com/api/v3/templates/{template}

Returns template configuration

Response attributes

response:
object Template object

Template object

id:
integer Template unique id
name:
string Template name
tags:
array Tags assigned to template
layout:
object Template layout configuration
pages:
array Template page configuration
dataSettings:
object Template data configuration

  curl -H "X-Auth-Key: $key" \
    -H "X-Auth-Workspace: $workspace" \
    -H "X-Auth-Signature: $signature" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -X GET https://pdfgeneratorapi.com/api/v3/templates/123456


  $client = new \GuzzleHttp\Client([
      'base_uri' => 'https://pdfgeneratorapi.com/api/v3/',
  ]);

  $response = $client->request('GET', 'templates/123456', [
    'headers' => [
      'X-Auth-Key' => $key,
      'X-Auth-Workspace' => $workspace,
      'X-Auth-Signature' => $signature
      'Accept' => 'application/json',
      'Content-Type' => 'application/json; charset=utf-8'
    ]
  ]);


{
  "response": {
    "id": "123456",
    "name": "My awesome template",
    "tags": "",
    "layout": {
      "format": "A4",
      "unit": "cm",
      "orientation": "portrait",
      "rotation": 0,
      "margins": {
        "top": 0.5,
        "left": 0.5,
        "right": 0.5,
        "bottom": 0.5
      },
      "emptyLabels": 0,
      "width": 21,
      "height": 29.7,
      "repeatLayout": null
    },
    "pages": [
      {
        "width": 21,
        "height": 29.7,
        "components": [
          {
            "width": 3.95,
            "height": 0.47,
            "top": 0.18,
            "left": 0.26,
            "zindex": 1005,
            "phpClassName": "Reports_Component_CustomText",
            "className": "CustomText",
            "name": "Text",
            "preview": null,
            "value": "Component value",
            "defaultValue": "{value}",
            "dataIndex": "randomDataIndexForFlexHeight",
            "borderStatus": {
              "top": true,
              "right": true,
              "bottom": true,
              "left": true
            },
            "borderWidth": 0,
            "borderColor": "#000000",
            "borderStyle": "none",
            "backgroundColor": "#ffffff",
            "useFlexHeight": true,
            "sortBy": [],
            "sortDir": "ASC",
            "filterBy": [],
            "groupBy": [],
            "pivotOn": [],
            "pivotColumns": [],
            "pivotValues": [],
            "userRights": {
              "canEdit": true,
              "canMove": true,
              "canRemove": true,
              "canResize": true
            },
            "fontFamily": "opensans",
            "fontAlign": "left",
            "fontSize": 12,
            "fontType": [],
            "fontColor": "#000000",
            "fontValign": "T",
            "conditionalFormats": []
          }
        ],
        "margins": {
          "right": 0.5,
          "bottom": 0.5
        },
        "border": false
      }
    ],
    "dataSettings": {
      "sortBy": [],
      "filterBy": []
    }
  }
}

Get document

POST https://pdfgeneratorapi.com/api/v3/templates/{template}/output

Merges template with data and returns base64 encoded document.
You can send json encoded data in request body or a public url to your json file as data parameter.

Request parameters

name:
string Document name, returned in meta data.
format:
string Document format.
Available formats: pdf, html
Default: pdf
data:
string Data to be merged with the template. This can be json encoded string or a url from where the API can fetch the data. Your data can also be an array of objects to generate multiple documents from one template.

If json encoded data is sent in request body then this value is not used.
Single PDF/HTML document is returned event if an array of objects is used.

Response attributes

response:
string Base64 encoded document.
meta:
object Document meta data.

Meta object

name:
string Document name. This value is automatically generated if name attribute is not defined in request.
display_name:
string Document name without the file extension.
encoding:
string Document encoding (e.g base64).
content-type:
string Document content type.

  $documentData = json_encode([
    [
      'documentNumber' => 1,
      'buyer' => ['name' => 'John Smith', 'email' => 'john@smith.com']
    ],
    [
      'documentNumber' => 2,
      'buyer' => ['name' => 'Jane Doe', 'email' => 'jane@doe.com']
    ]
  ]);


  /**
   * Data in request body
   */
  curl -H "X-Auth-Key: $key" \
    -H "X-Auth-Workspace: $workspace" \
    -H "X-Auth-Signature: $signature" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d "$documentData" \
    -X POST  https://pdfgeneratorapi.com/api/v3/templates/123456/output

  /**
   * Data url in query string
   */
  curl -H "X-Auth-Key: $key" \
    -H "X-Auth-Workspace: $workspace" \
    -H "X-Auth-Signature: $signature" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -X POST https://pdfgeneratorapi.com/api/v3/templates/123456/output?data=https://myawesomeapp.com/data/9129381823.json

  /**
   * Data url in post param
   */
  curl -H "X-Auth-Key: $key" \
    -H "X-Auth-Workspace: $workspace" \
    -H "X-Auth-Signature: $signature" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d "data=https://myawesomeapp.com/data/9129381823.json" \
    -X POST https://pdfgeneratorapi.com/api/v3/templates/123456/output


  $client = new \GuzzleHttp\Client([
      'base_uri' => 'https://pdfgeneratorapi.com/api/v3/',
      'options' => [
        'headers' => [
          'X-Auth-Key' => $key,
          'X-Auth-Workspace' => $workspace,
          'X-Auth-Signature' => $signature,
          'Accept' => 'application/json',
          'Content-Type' => 'application/json; charset=utf-8',
        ]
      ]
  ]);

  /**
   * Data in request body
   */
  $response = $client->request('POST', $resource, [
    'body' => $documentData
  ]);

  /**
   * Data url in query string
   */
  $response = $client->request('POST', $resource, [
    'query' => [
      'data' => 'https://myawesomeapp.com/data/9129381823.json'
    ]
  ]);

  /**
   * Data url in post param
   */
  $response = $client->request('POST', $resource, [
    'form_params' => [
      'data' => 'https://myawesomeapp.com/data/9129381823.json'
    ]
  ]);


{
  "response": "JVBERi0xLjcKJeLjz9MKNyAwIG9iago8PCAvVHlwZSA...",
  "meta": {
    "name": "a2bd25b8921f3dc7a440fd7f427f90a4.pdf",
    "display_name": "a2bd25b8921f3dc7a440fd7f427f90a4",
    "encoding": "base64",
    "content-type": "application\/pdf"
  }
}

Open editor

GET https://pdfgeneratorapi.com/api/v3/templates/{template}/editor

Opens template in document editor. You need to redirect user to created url (redirect or POST form).

Request parameters

data:
string Data to be used for preview in editor. This can be json encoded string or a url from where the API can fetch the data.

  REDIRECT https://pdfgeneratorapi.com/api/v3/templates/123456/editor?key=$key&workspace=$workspace&signature=$signature&data=https://myawesomeapp.com/data/9129381823.json


  $url = 'https://pdfgeneratorapi.com/api/v3/templates/123456/editor?key={$key}&workspace={$workspace}&signature={$signature}&data=https://myawesomeapp.com/data/9129381823.json';
  header('Location: {url}');
  exit;

Create template

POST https://pdfgeneratorapi.com/api/v3/templates

Creates a blank template with given name. Template is placed to the workspace specified in authentication params.
Template data must be sent in request body.

Request object

name:
string Template name

Response attributes

response:
object Template object

Template object

id:
integer Template unique id
name:
string Template name
tags:
array Tags assigned to template
layout:
object Template layout configuration
pages:
array Template page configuration
dataSettings:
object Template data configuration

  $documentData = json_encode([
    'name' => 'My new template'
  ]);


  curl -H "X-Auth-Key: $key" \
    -H "X-Auth-Workspace: $workspace" \
    -H "X-Auth-Signature: $signature" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d "$documentData" \
    -X  POST https://pdfgeneratorapi.com/api/v3/templates


  $client = new \GuzzleHttp\Client([
      'base_uri' => 'https://pdfgeneratorapi.com/api/v3/',
  ]);

  $response = $client->request('POST', 'templates', [
    'body' => $documentData,
    'headers' => [
      'X-Auth-Key' => $key,
      'X-Auth-Workspace' => $workspace,
      'X-Auth-Signature' => $signature
      'Accept' => 'application/json',
      'Content-Type' => 'application/json; charset=utf-8'
    ]
  ]);


{
  "response": {
    "id": "24386",
    "name": "My new template",
    "tags": null,
    "layout": {
      "format": "A4",
      "unit": "cm",
      "orientation": "portrait",
      "rotation": 0,
      "margins": {
        "top": 0,
        "left": 0,
        "right": 0,
        "bottom": 0
      },
      "emptyLabels": 0,
      "width": 21,
      "height": 29.7,
      "repeatLayout": null
    },
    "pages": [
      {
        "width": 21,
        "height": 29.7,
        "components": [],
        "margins": {
            "right": 0,
            "bottom": 0
        },
        "border": false
      }
    ],
    "dataSettings": {
      "sortBy": [],
      "filterBy": []
    }
  }
}

Copy template

POST https://pdfgeneratorapi.com/api/v3/templates/{template}/copy

Creates a copy of a template to the workspace specified in authentication params.

Request params

name:
string New name for the copied template

Response attributes

response:
object Template object

Template object

id:
integer Template unique id
name:
string Template name
tags:
array Tags assigned to template
layout:
object Template layout configuration
pages:
array Template page configuration
dataSettings:
object Template data configuration

  curl -H "X-Auth-Key: $key" \
    -H "X-Auth-Workspace: $workspace" \
    -H "X-Auth-Signature: $signature" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d "name=Copied template" \
    -X  POST https://pdfgeneratorapi.com/api/v3/templates/123456/copy


  $client = new \GuzzleHttp\Client([
      'base_uri' => 'https://pdfgeneratorapi.com/api/v3/',
  ]);

  $response = $client->request('POST', 'templates/123456/copy', [
    'form_params' => [
      'name' => 'Copied template'
    ],
    'headers' => [
      'X-Auth-Key' => $key,
      'X-Auth-Workspace' => $workspace,
      'X-Auth-Signature' => $signature
      'Accept' => 'application/json',
      'Content-Type' => 'application/json; charset=utf-8'
    ]
  ]);


{
  "response": {
    "id": "24387",
    "name": "Copied template",
    "tags": "",
    "layout": {
      "format": "A4",
      "unit": "cm",
      "orientation": "portrait",
      "rotation": 0,
      "margins": {
        "top": 0.5,
        "left": 0.5,
        "right": 0.5,
        "bottom": 0.5
      },
      "emptyLabels": 0,
      "width": 21,
      "height": 29.7,
      "repeatLayout": null
    },
    "pages": [
      {
        "width": 21,
        "height": 29.7,
        "components": [
          {
            "width": 3.95,
            "height": 0.47,
            "top": 0.18,
            "left": 0.26,
            "zindex": 1005,
            "phpClassName": "Reports_Component_CustomText",
            "className": "CustomText",
            "name": "Text",
            "preview": null,
            "value": "Component value",
            "defaultValue": "{value}",
            "dataIndex": "randomDataIndexForFlexHeight",
            "borderStatus": {
              "top": true,
              "right": true,
              "bottom": true,
              "left": true
            },
            "borderWidth": 0,
            "borderColor": "#000000",
            "borderStyle": "none",
            "backgroundColor": "#ffffff",
            "useFlexHeight": true,
            "sortBy": [],
            "sortDir": "ASC",
            "filterBy": [],
            "groupBy": [],
            "pivotOn": [],
            "pivotColumns": [],
            "pivotValues": [],
            "userRights": {
              "canEdit": true,
              "canMove": true,
              "canRemove": true,
              "canResize": true
            },
            "fontFamily": "opensans",
            "fontAlign": "left",
            "fontSize": 12,
            "fontType": [],
            "fontColor": "#000000",
            "fontValign": "T",
            "conditionalFormats": []
          }
        ],
        "margins": {
          "right": 0.5,
          "bottom": 0.5
        },
        "border": false
      }
    ],
    "dataSettings": {
      "sortBy": [],
      "filterBy": []
    }
  }
}

Get template

DELETE https://pdfgeneratorapi.com/api/v3/templates/{template}

Deletes template

Response attributes

response:
object

  curl -H "X-Auth-Key: $key" \
    -H "X-Auth-Workspace: $workspace" \
    -H "X-Auth-Signature: $signature" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -X GET https://pdfgeneratorapi.com/api/v3/templates/123456


  $client = new \GuzzleHttp\Client([
      'base_uri' => 'https://pdfgeneratorapi.com/api/v3/',
  ]);

  $response = $client->request('DELETE', 'templates/123456', [
    'headers' => [
      'X-Auth-Key' => $key,
      'X-Auth-Workspace' => $workspace,
      'X-Auth-Signature' => $signature
      'Accept' => 'application/json',
      'Content-Type' => 'application/json; charset=utf-8'
    ]
  ]);


{
  "response": {
    "success": true
  }
}

Error codes

Errors are returned using HTTP error code syntax. All additional information about the error is sent in response body.

Code Description
401 Authentication failed
401 Required parameter missing
403 Access not granted
404 Entity not found
404 Resource not found
422 Incorrect parameter value
500 Internal error

Response attributes

error:
string Error description
status:
integer Error status code

# Response
{
  "error": "Authentication failed: key missing",
  "status": 401
}

Expression language

Expression language is PDF Generator API specific programming language that allows to write mathematical and logical expression to manipulate the value displayed by component.

Example expression: {% 2 + {dataFieldName} + {dataFieldName2}*0.5 %}

Supported operators

Arithmetic Operators

  • + (addition)
  • – (subtraction)
  • * (multiplication)
  • / (division)
  • % (modulus)
  • ** (pow)

Bitwise Operators

  • & (and)
  • | (or)
  • ^ (xor)

Comparison Operators

  • == (equal)
  • === (identical)
  • != (not equal)
  • !== (not identical)
  • < (less than) > (greater than)
  • <= (less than or equal to) >= (greater than or equal to)

Array

  • in (contain)
  • not in (does not contain)

String

  • ~ (concatenation)

Ternary Operators

  • {% {financial_status} === 'paid' ? 'All paid' : 'Waiting for payment' %}

Functions

Uppercase

To display data field value in uppercase, use following expression.
{% uppercase({dataFieldName}) %}

Lowercase

To display data field value in lowercase, use following expression.
{% lowercase({dataFieldName}) %}

Capitalize

Uppercase the first character of each word in a string.
{% capitalize({dataFieldName}) %}

Example: {% capitalize('hello word') %} => Hello Word

Sum

It is possible to calculate sum of table column using following code
{% sum({line_items::amount}) %}

Sumproduct

The sumproduct function multiplies the corresponding items in the arrays and returns the sum of the results.
{% sumproduct({line_items::amount},{line_items::price}, {line_items::anotherColumn}) %}

Average

It is possible to calculate average of table column using following code
{% avg({line_items::amount}) %}

Count

It is possible to count number of items in list
{% count({line_items}) > 3 ? 'More than three' : 'Less than three' %}

Empty

The empty function checks if field has value.
{% empty({dataField}) ? 'No value' : 'Field has value' %}

Join

The join function concatenates field values with specified separator. Last arguments is always used as the separator.
{% join(";", {field1}, {field2}, {field3}, ..., {fieldN}) %}

Date

Format date value. NB! You need to use the Date formatter.
{% date({dateString}, {timezone}, {addDays}, {outputFormat}) %}

Datetime

Format datetime value. NB! You need to use the Date formatter.
{% datetime({datetimeString}, {timezone}, {addDays}, {outputFormat}) %}

Max

Returns maximum value of list of elements or separate field values.
{% max({line_items::quantity}) %} or {% max({dataField1}, {dataField2}, ..., {dataFieldN}) %}

Min

Returns minimum value of list of elements or separate field values.
{% min({line_items::quantity}) %} or {% min({dataField1}, {dataField2}, ..., {dataFieldN}) %}

Iterate list of elements (array map)

Iterates over list of elements and executes expression for each element. Returns new list.
{% iterate({line_items}, '{quantity}*{price}') %}