pdfToolbox in the Cloud for OEM partners

pdfToolbox in the Cloud is a callas software solution that is reserved exclusively for OEM partners. If this solution could be interesting for you, there is a fully-functional trial and free support available so you can evaluate it. Fill out the form on the callas software website for OEM partners and we will get back to you ASAP. In the mean time, don't hesitate to read through the documentation already.

What is pdfToolbox in the Cloud?

In many cases it is easiest to use a command line version, or an SDK version of pdfToolbox to integrate with an existing solution; this is what the majority of the callas OEM partners chose. In other cases, having pdfToolbox available in the cloud as a full SaaS solution can be preferable. pdfToolbox in the Cloud has a number of marked advantages over other versions:

  • You don't have to worry about software or hardware. The solution is managed within the AWS environment by callas software.
  • If your documents are already living in the Cloud, simply calling a ReST API allows integrating the full power of pdfToolbox.
  • Different from the command-line or SDK versions, pdfToolbox in the Cloud already implements queueing of requests, so you can start multiple requests in parallel for fastest processing.

This documentation is focused on the technical details of pdfToolbox in the Cloud; contact us to discuss licensing and business topics.

Exploring pdfToolbox in the Cloud

The documentation you are reading contains the technical details about pdfToolbox in the Cloud. It details how the API works, how you should structure calls, how authentication works, and how you can get results back in your solution. Along with this documentation, you can use the HTML-based demo client to see how an integration works, and experiment with the different calls.

For most calls, you'll need an API key, which you can get from us by filling out the form.

To use the demo implementation, follow the link to the start web page.

Examples in this documentation

The API is not restricted to any particular language or library; as long as you can make and receive regular ReST API calls (all calls are either GET or POST HTTP requests), you are able to use pdfToolbox in the Cloud.

For clarity and consistency, all examples in this documentation are presented using cURL.

URL format

URLs are composed of  …

  • the scheme part (https)
  • the server part (api.callassoftware.io)
  • the path part (depends on the resource to be used)

examples …

  • https://api.callassoftware.io/v1/pdfToolbox
  • https://api.callassoftware.io/v1/pdfToolbox/saveasimg
  • https://api.callassoftware.io/v1/result/5a56290d-8422-4bfb-a95f-792656ddefc4

Many responses bodies contain a path component that is to be used in subsequent requests. It depends on the used framework (or client) library whether this path can be used as-is, or if it is necessary to prepend it with the scheme and/or the server part.

HTTP Messages

All data is exchanged using the JavaScript Object Notation (aka JSON).

Request Body example

Only POST requests have a message body.

{
  "finput": "https://s3.eu-central-1.amazonaws.com/ccapi-sample/sample.pdf",
  "imgformat": "PNG"
}
Click to copy

Response Body example 

{
    "message": "operation enqueued for asynchronous processing (keep going using a GET on the belonging path ...)",
    "ms_retry_after": 200,
    "operation": "saveasimg",
    "path": "https://node5.brb234ay220.de/v1/result/4a56290d-8422-4bfb-a95f-792656ddefc4",
    "progress": 0,
    "state": "INITIAL"
}
Click to copy

HTTP Status Codes

Status Code
 Meaning
 Comment
202 Accepted
 Operation is pending
4xx
 Client Error Error caused by client. The user should examine the error cause and try to fix it
200 OK Operation completed successfully
5xx Server Error Internal server error. Not fixable by the user

Get a list of operations

A list of available operations is received by submitting a GET request.

Request 

curl -X GET https://api.callassoftware.io/v1/pdfToolbox
Click to copy

Response 

{
  "message": "available operations",
  "externalDocs": {
        "description" : "Available Operations",
        "url" : "https://www.callassoftware.com/en/pdftoolboxinthecloud-howto"
   },
  "operations": [
    {
      "name": "preflight",
      "description": "preflight an input file and save results with or without reports",
      "path": "https://api.callassoftware.io/v1/pdfToolbox/preflight"
    },
    {
	"name": "preflight_vars",
	"description": "retrieve variable keys from a pdfToolbox profile",
	"externalDocs": {
		"description": "Enumprofiles Details",
		"url": " https://www.callassoftware.com/goto/tbx_ENG_cloud_enumprofiles"
			},
	"path": "https://api.callassoftware.io/v1/pdfToolbox/preflight_vars"
		},
    {
	"name": "saveasimg",
	"description": "save an input file as images (one per page)",
	"externalDocs": {
		"description": "SaveAsImage Details",
		"url": "https://www.callassoftware.com/goto/tbx_ENG_cloud_saveasimg"
			},
	"path": "https://api.callassoftware.io/v1/pdfToolbox/saveasimg"
	},
    {
	"name": "splitlayers",
	"description": "split layers into single PDFs (one per layer)",
	"externalDocs": {
		"description": "Split Layers Details",
		"url": "https://www.callassoftware.com/goto/tbx_ENG_cloud_splitlayers"
			},
	"path": "https://api.callassoftware.io/v1/pdfToolbox/splitlayers"
	},
    {
	"name": "dieline",
	"description": "extract dieline(s) from PDF",
	"externalDocs": {
		"description": "Extract Dieline Details",
		"url": "https://www.callassoftware.com/goto/tbx_ENG_cloud_dieline"
			},
	"path": "https://api.callassoftware.io/v1/pdfToolbox/dieline"
	},
	{
	"name": "splitatmark",
	"description": "split PDF at mark",
	"externalDocs": {
		"description": "splitatmark Details",
		"url": "https://www.callassoftware.com/goto/tbx_ENG_cloud_splitatmark"
			},
	"path": "https://api.callassoftware.io/v1/pdfToolbox/splitatmark"
	}
  ]
}
Click to copy

Get a list of operation parameters

Each operation has at least one mandatory and possibly some optional parameters. A description of these parameters is received by submitting a GET request to the operation path.

curl https://api.callassoftware.io/v1/pdfToolbox/saveasimg
Click to copy

Post an operation and fetch the result

For a POST request, an x-api-key header field needs to be provided that can be obtained from callas software. The typical "workflow" for e.g. a saveasimg operation is like below (in a pseudocode "language")

response = POST https://api.callassoftware.io/v1/pdfToolbox/saveasimg
while (${response.statuscode} == 202):
    if (${response.body} contains ms_retry_after): delay ${response.body.ms_retry_after}
    response = GET https://api.callassoftware.io/${response.body.path}
if (${response.statuscode} == 200):
    GET ${response.body.result_url}
else:
    console.log an error occured. See ${response.body.message}
Click to copy

Further details on POSTing a request.