PDF REST APIs

PDF REST APIs

API Reference Guide

We provide an online reference for working with the PDF REST APIs.

Getting started

This guide explains how to use our PDF REST APIs. This service provides RESTful APIs, allowing you to interact with a server at specific URLs, or endpoints, by sending requests. We will explore how to send POST requests to process documents and GET requests to retrieve output.

API key

In order to begin your free trial with PDF REST APIs, you will need an API key. If you don't have a key, please complete this form to receive one by email. While using the API service, you will need to include this key in each of your POST requests as a header called Api-Key.

Your key will become invalid after your trial period expires or after you reach 500 requests. Requests using an invalid key return a 401 error. If you wish to extend your API key, send a message to cloud@datalogics.com.

Postman

Parts of this demonstration will use Postman, a free platform used to issue GET and POST requests for API processing. You can download Postman here.

cURL

This guide also includes a command-line example using Client for URLs, or cURL. cURL is a command line tool used for transferring files between various Internet protocols using the URL syntax. You can check for an installed version of cURL using the following command:

curl --version
If cURL is not found, then you can download it here.

Introduction to PDF REST APIs

We offer a collection of PDF REST APIs comprised of various endpoints (essentially, URLs). Each endpoint represents a different action that can be performed by requests that are sent to these endpoints. Note that the root URL is the same for all endpoints (https://cloud-api.datalogics.com), so actions are determined by the final "endpoint" of the URL path (such as /pdf, /merged-pdf, or /zip). The kind of processing or conversion carried out by each endpoint is implied by its name. For example, /jpg converts one or more pages of an input PDF to a JPG file.

All but one of the PDF REST API endpoints accept POST requests in order to process one or more input files. The exception is /resource, which is responsible for returning processed or converted files by way of GET requests.

Our reference guide includes a description of each endpoint and its parameters. For now, let us focus on just a few endpoints.

Uploading and downloading files

You can submit API requests several ways. We offer two methods to introduce you to working with PDF REST APIs: command line tools and the Postman software.

You may want to explore other more programmatic methods for submitting requests, such as Ajax, jQuery, or Axios.

Using Postman
Getting started with Postman

Using an API platform such as Postman can make it easy to visualize and edit requests. If you don’t already use Postman, start by downloading and installing the Postman app. Then, create a Postman account.

This example uses the split-pdf endpoint to split a PDF into individual documents, each consisting of a single page of the input document.

Creating a workspace and collection

Create a workspace and then select that workspace before you can create a request.

Open Postman, and navigate to Workspaces → Create Workspace on the top of the screen.

Click .  The Create workspace screen appears.

Enter a name for your Workspace. We suggest “PDF REST APIs.” Then, select a visibility setting.

Choose Personal for this example. When you are ready, click .

You should now see your new workspace under the Workspaces dropdown menu.

Click PDF REST APIs to make sure that the Workspace is active.

We recommend you create a Collection within the Workspace where you can group your requests together. Select Collections on the side of the screen.

Click or the + button in the top left corner:

You may rename your request by right-clicking and selecting Rename in the context menu.

Sending a POST request

Below your Collection, click Add Request to open a new tab.

For more requests, you can right-click your Collection and select Add Request again in the context menu.

Specify the type of request, and the location to send it to. In the request tab, click the dropdown menu to the left of the URL text field and select POST.

Insert https://cloud-api.datalogics.com/split-pdf into the request URL text field.

Below the URL, click Headers to view a table of key-value pairs. Add the headers as shown below, substituting in the value of your API key.

Postman will add additional rows as you fill existing rows.

Next, click Body, and then click the form-data radio button to view another table of key-value pairs. This is where you need to put your input file and parameters.

To add a file, hover over an empty Key cell to reveal a dropdown. By default, the value should read Text; select File instead.

You should now see a button in the Value column called Select Files. Clicking this button opens a dialog where you can browse for the directory where your input file is stored.

The remaining keys should be Text entries. To provide an output file, you don't need to select and import a file from your computer. The process will create the output file for you. So all you need to do is type in the name you want to assign to the output file in the Value field when your process generates it.

Use the image below as a reference to add the input file and parameters:

The parameters should be in lower case letters.  Include brackets if applicable.

Refer to our reference guide for a list of other available requests and the required parameters.

We happened to use a PDF consisting of five pages, but any number of pages will do here.

You may omit a parameter from your request by leaving the checkbox beside it unchecked. For example, we added the pages[] parameter and then disabled it. This will generate one output file for every page in the input document, the default setting for pages[].

Later, if you want to include this parameter, you can simply check the box to enable it. Then you could use the pages[] parameter one or more times to include only the pages you would like in each output file.

You are now ready to send this request! Click the Send button:

A JSON response should appear in the bottom region of the window. If no errors are raised, your response should look something like this:

{
"outputUrl": [
"https://cloud-api.datalogics.com/resource/012345678-9abc-def0-1234-56789abcdef0?format=file",
"https://cloud-api.datalogics.com/resource/123456789-abcd-ef01-2345-6789abcdef01?format=file",
"https://cloud-api.datalogics.com/resource/234567890-8abc-fed9-3456-66789abcdef0?format=file",
"https://cloud-api.datalogics.com/resource/f9affa999-bcdd-abc1-1234-712225722233?format=file",
"https://cloud-api.datalogics.com/resource/345678901-feee-ed54-1234-36789abcdef0?format=file"
],
"outputId": [
"012345678-9abc-def0-1234-56789abcdef0",
"123456789-abcd-ef01-2345-6789abcdef01",
"234567890-8abc-fed9-3456-66789abcdef0",
"f9affa999-bcdd-abc1-1234-712225722233",
"345678901-feee-ed54-1234-36789abcdef0"
],
"inputId": "6789012345-abcd-ef01-2345-98765abcdef0"
}

Because the input PDF was split into one document per each of its five pages, there are five download links and five IDs.

You may wish to save this request to your collection to edit and run later. To save your request, click Save above the URL field.

Getting output files

Clicking on any link within the response will automatically open a new tab in Postman for a GET request to the resource endpoint. Click Send to submit the request.

To save the returned file, click Save Response → Save to a file in the response window.

Alternatively, you may copy URLs from the contents of outputUrl into your web browser.

Note that while POST requests count against your total API request limit, GET requests do not require your API key and do not count against your limit.

Using a command-line tool

You may also send requests by using software on the command line, such as cURL. You can use cURL on a command-line interface, such as Windows Command Prompt (cmd.exe) and Terminal on Mac. Entering a request using cURL can be helpful in understanding each component of a request.

Sending a POST request

Suppose you want to convert a single-page PDF document into a PNG graphic file. Let's assemble a POST request, starting with the following fragment. Don't run this command just yet!

curl -X POST 'https://cloud-api.datalogics.com/png' -H 'Accept: application/json' -H 'Content-Type: multipart/form-data'
Begin by specifying a POST request to the PNG endpoint. Then, add two necessary header parameters with the -H flag so that both the client (you) and server know what kind of data to expect.

The next step is to add body parameters. This endpoint requires two parameters: an input file and an output name. Both are added using the -F flag:

-F 'file=@"path/to/mydocument.pdf"' -F 'output="myjpg"'

From here, you can add optional parameters. For instance, you can specify the color model of your output PNG:

-F 'color_model=gray'

This will override the default value, "rgb".

Finally, you must add the API key as a header, again using the -H flag:

-H 'Api-Key: xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

Fully assembled, the command now looks like this:

curl -X POST 'https://cloud-api.datalogics.com/png' -H 'Accept: application/json' -H 'Content-Type: multipart/form-data' -H 'Api-Key: xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' -F 'file=@"path/to/mydocument.pdf"' -F 'output="myjpg"' -F 'color_model=gray'

You can now run this command to submit your request by pressing Enter. Assuming no error is returned, the JSON response will look something like this:

{
"outputUrl": "https://cloud-api.datalogics.com/resource/012345678-9012-3456-7890-123456789abc?format=file",
"outputId": "012345678-9012-3456-7890-123456789abc",
"inputId": "123456789-abcd-ef01-2345-6789abcdef01"
}

Some endpoints accept and/or return multiple files. In those cases, one or more of the above keys in JSON will be arrays containing multiple values.

You now have a link where you can download your output file! This can be done either by copying the value of outputUrl into your web browser or by submitting a GET request to that location.

Sending a GET request

Below is the request that downloads the output file from our POST example to the location /path/to/mypng.png:

curl -X GET "https://cloud-api.datalogics.com/resource/012345678-9012-3456-7890-123456789abc?format=file" --output /path/to/mypng.png
You must retrieve the file before it is automatically removed from the server. All files are deleted after ten minutes.

Using generated file IDs

Every file stored on the server is given a unique ID code. You may refer to a file ID in a request instead of the file link by substituting "id" for "file".

Using cURL, the "id" flag will look something like this:

-F 'id="012345678-9abc-def0-1234-56789abcdef0"'
In Postman, replace "file" with "id" in the Key column in the body of the request. In the Value column dropdown, change File back to Text.

This allows you to string together successive operations in your document processing workflow. For example, you could convert a Word document to PDF, merge this output with a separate PDF, and convert the resulting output to PDF/A. This results in fewer file uploads and downloads and overall greater efficiency.

Please note that files are automatically deleted from the server after ten minutes. Attempting to retrieve a file by its ID after the file has expired will result in an error: ZZ

{
"error": "The file does not exist."
}

Submitting feedback

We appreciate any and all feedback about your trial experience. If you have questions or comments, or you wish to extend your API trial key, please contact our Datalogics Support representatives at cloud@datalogics.com.