Skip to main content

Getting started with the Pdftools API

The Pdftools API is a set of REST APIs that allows you to manage and implement document lifecycle workflows. Using this API, you can convert or compress images and PDFs to various formats, optimize PDFs, add custom stamps, and validate PDF standards. This guide will help you make your first request to the Pdftools API.

Before you start

Obtain an API key. Every call to the Pdftools API must include the API key.

  1. Request the API key at the Pdftools API product page.
  2. Check the email for the API key.
Want to jump straight to the code?

Skip the quickstart and Get started with code samples.

Quickstart without coding

Start using the Pdftools API with Postman. The Postman collection allows you to pre-load API request configurations to send API calls without manually setting all parameters. After you include your API key, the rest of the values are saved as prefilled variables, making it easy to prepare your next call. To start using the Postman collection:

  1. Install a Postman client.
  2. Click the following link to download the Postman collection.
  3. In Postman, import the collection.
  4. Follow the instructions displayed in the Postman application.

Authenticate in Postman

To authenticate the Pdftools API in the Postman collection, add your API key:

  1. In Postman, go to Collections > Pdftools API > Authorization.
  2. Ensure that the type is set as Api Key and the key is X-Api-Key.
  3. In the Value field, add the value of your API key, and then click Save.

For more details, see Import data into Postman in Postman documentation.

Use Pdftools API with Postman

Quickstart with a PDF file

Use a PDF file in the following procedure.

Follow the instructions below to get your API calls running:

  1. In the Pdftools API Postman collection, go to Step 1: Upload > From local > POST Get Upload URL.
  2. Click Body and change the input.pdf to the name of the file you want to upload, and then click Send.
  3. Go to PUT Upload Local File, and then click Body > Select file.
  4. Select a local file you want to process, and then click Send.
  5. Go to Step 2: Operations > Optimize, and then click Send.
  6. Go to Step 3: Result > GET Get Result, and then click Send.
  7. In the response body (marked as Body in Postman), open the URL link in the url field.

Getting started with code

Examles for every operation can be found on the Operations section, for example you can check the Compress and optimize example.

1. Authenticate API calls

Include the API key in the request header of all API calls as a value of the following key:

X-Api-Key: <API-KEY-VALUE>

Substitute <API-KEY-VALUE> with the value of your API key.

2. Get upload URL

Send the following API call to get the upload URL.

info

Substitute the input.pdf value with the file name and file format of the file you want to upload.

curl -L -X POST 'https://api.pdf-tools.com/v1-beta/files/upload/fromLocal' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'X-Api-Key: <API_KEY_VALUE>' \
--data-raw '{
"fileName": "input.pdf"
}'

You receive the response in the following format:

{
"fileId": "101be847-f838-4361-9e27-27030291a329",
"uploadUrl": "https://pdftools-production-developer-platform.s3.eu-west-1.amazonaws.com/default/files/101be847-f838-4361-9e27-27030291a329/input.pdf?X-Amz-Expires=86400&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEPT%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCWV1LXdlc3QtMSJIMEYCIQDqNPVM3caocGj5ZtjwsYJA2Zu2%2F4QW06OG7lFCIlNclgIhAJXuDD7LC6L5sL7Vcao7OwmAhESK%2FxYV3dmAdDPfUp89Kv4DCI3%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEQARoMMTQ3OTQzNjQ3NTQ3IgzNEKXYvICfx2u9aV8q0gOxMVkaCcSJCRGKGcDGT7lwQXbL5aFY9tSEjZ5Gk4tMAmsOtALNPxSbdFmbI8PLozyUSEeY4%2FnJqii4v969lvEXAcfCyHDT6375gon0HbifFTR32dw60Thq4KhxLNoFCxiVrGQWWQa%2FN6rxrh1%2B4hQFX1ceFp0Gk7cguNNNOYNgisAMs90w%2FZXLxMO7V5MnRGOsKKsMJ27HMXtIX%2FotAum2%2BGH%2B4Hh97QMHQ%2F65RkOEgzqaE6LpqB1Xm9VllFg%2Bsm6Jx1zjS30MvC7VtGZvygmD%2Fkfa9ayjuwKsRSjBbmKOYYdqhoxswbzhj4MowW%2BBDO0LbsG48rR3hNbFNftXCVEGyt8hkr5oSu4egLiirBjG3OnUJ9%2BmcT6lSDha5Qth2%2ByKq2EKcGS1v0HgfmFtLcOmHKbZH6zj7S%2BjlRGYe7QgyFAACvp%2F3Bc8AjLp6dIMrZy%2BaXaPSg5ClUgUdki%2FKQWTAwWI%2FPay7FTmGHg23yoo64jITz3nCSTj93T7EP2XN9wc1dFNL6Hmq%2BU65Ocubmt3G5IsX3l5LaFJ3R11txOl0o%2F%2FGfNDvd%2FFRyx9RLfYPdUNeTrrZdU%2B2gcbTjSTMgxWPd81dA0lN7gEut7J4m7NWmPGMPvf36wGOqQB3GAHZl2V3WrH1v5lJnxkASwfqjyY1llVhvpk2iHCXnOC8pPaQcnmlzQWRcVJHC%2FXXMZ6vha%2B4solrPc9dq2%2B4ztvszQu9XG9bY2BFrcgV2TsIF9tGFrZAIUdEbBRX4oxBcbgBH8VAIGR2UiUxup8jM%2FeiQehjVYglJDTsZ3KN1YvenCl8FhlIVJhCcIuVnE3O80j5QENjFstB9xEc%2F4myQktmnU%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIASE4RA5E5Q7OUXDEZ/20240105/eu-west-1/s3/aws4_request&X-Amz-Date=20240105T132626Z&X-Amz-SignedHeaders=host&X-Amz-Signature=ae108083ecca0d44656507a2235e0b722ffaba44e98d2b7d8eeed7c107b4fbf8"
}
Upload from URL

You can also upload a file from a URL. For more information, see the Upload file from URL in the API reference.

3. Upload local file

Upload a file to a URL. You received the URL as an uploadUrl in the response of the call described in the previous section.

curl --location --request PUT '<UPLOAD_URL>' \
--header 'Content-Type: application/octet-stream' \
--data '@<PATH_TO_LOCAL_FILE>'

If the API call is successful, you receive the HTTP 200 status code.

4. Compress and optimize

Run the compression and optimization operation. Replace <FILE_ID> with fileId received in the response of the upload call.

curl -L -X POST 'https://api.pdf-tools.com/v1-beta/operations/optimize' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'X-Api-Key: <API_KEY_VALUE>' \
--data-raw '{
"options": {
"password": "password",
"profile": "archive"
},
"input": {
"fileId": "<FILE_ID>"
}
}'

See the following example response:

{
"operationId": "f8418394-73f1-4ad4-8bb2-cda3ad9ff785",
"operationType": "optimize",
"operationStatus": "inProgress"
}

5. Get the result

To get the result, use the operationId to call the result endpoint:

curl -L -X GET 'https://api.pdf-tools.com/v1-beta/operations/<OPERATION_ID>/result' \
-H 'Accept: application/json' \
-H 'X-Api-Key: <API_KEY_VALUE>'
Operation is in progress

If the operation status is inProgress, call the result endpoint again after some time. The time necessary to finish the operation processing depends mainly on the size and complexity of the uploaded files.

When the operation is finished, you receive the following result:

{
"operationType": "optimize",
"operationStatus": "finished",
"outputFile": {
"fileId": "532e9577-e943-4957-9d67-d3f04b128978",
"name": "output.pdf",
"url": "www.exampleurl/output.pdf"
}
}

Download the result file from outputFile.url property.

Optional: 6. Chain multiple operations

Chain successive operations without downloading and uploading result files between operations. For example, add a stamp to a PDF. See the list of available operations in the Perform the operation section.

To create a successive operation, use the outputFile.fileId from the response of the get results endpoint as input for another operation.

6.1. Chain multiple operations with Postman

Before you start

This section uses Postman and the Pdftools API Postman collection. Follow the steps to download and authenticate the Postman collection before you follow the procedure in this section. See Quickstart without coding for the necessary steps.

tip

Use PNG, JPEG, or TIFF in the following procedure.

Chain multiple operations on the same file through Pdftools API using Postman. The following procedure explains how to convert an image to PDF and then optimize it:

  1. In Postman, go to the Pdftools API Postman collection, go to Step 1: Upload > From local > POST Get Upload URL.
  2. Click Body and change the input.pdf to the name and format of the file you want to upload, and then click Send.
  3. Go to PUT Upload Local File, and then click Body > Select file.
  4. Select a local file you want to process, and then click Send.
  5. Go to Step 2: Operations > Convert > POST Convert Image to PDF, and then click Send.
  6. Go to Step 3: Result > GET Get Result, and then click Send.
  7. From the received response body, copy the value of fileId (for example 67283s-673e-4ix9-a628-01k8291id190c).
  8. Go to Step 2: Operations > Optimize, and then click the Body.
  9. Paste the value of fileId over {{fileId}}, and then click Send.
  10. Go to Step 3: Result > GET Get result, and then click Send.
  11. In the response body (marked as Body in Postman), open the URL link in the url field.

Additional information

Data retention period

All results of operations (files processed by the Pdftools API) and uploaded files have an expiration period. Uploaded and processed files are automatically deleted after one day. To start the operation on a particular file again, reupload the file and restart the operation.

API limitations

API key is limited to 5000 API requests per month and 10 requests per second. If you exceed the number of requests or want limits increased, contact us at pdftools-api@pdf-tools.com.

API workflow overview

The following diagram displays a simplified API workflow with specified request types:

API call process

Use API reference

See the documentation of required and optional fields, example requests, and responses in API reference.