Getting Started with Python

PSPDFKit API is offered as a simple HTTP API, so using it from Python is as easy as making an HTTP request. The following will guide you through how to install the required dependencies, and it’ll show you how to make a request.

This guide uses the requests HTTP library. Keep in mind that you can use any HTTP client you want; this example uses requests to demonstrate the principles of interacting with PSPDFKit API.

First, you need to make sure you have all the dependencies set up:

Shell
python -m pip install requests

You’ll also need to add document.pdf and logo.png files to the root of your Python project (the same folder you’ll be creating the pspdfkit.py file in). You can use the sample files provided by us — document.pdf and logo.png — or use your own.

Now that you have your dependencies and assets set up, you’re ready to start making requests to PSPDFKit API.

First, create a pspdfkit.py file which will contain your code to call PSPDFKit API. You can immediately import your dependencies as well:

Python
import requests
import json

Next, you’ll prepare the payload.

Preparing the Payload

You can create your instructions object:

Python
instructions = {
  'parts': [
    {
      'file': 'document'
    }
  ],
  'actions': [
    {
      'type': 'watermark',
      'image': 'company-logo',
      'width': '50%'
    },
    {
      'type': 'watermark',
      'text': 'Property of PSPDFKit',
      'width': 150,
      'height': 20,
      'left': 0,
      'bottom': '100%'
    }
  ]
}

payload = {
  'instructions': json.dumps(instructions)
}

Since PSPDFKit API expects the instructions to be a JSON object, you first create a dictionary that you then convert to a JSON object using the json.dumps function. In this example, you’ll be adding an image watermark. For more details on the available options specifically related to watermarking, refer to our watermarking guide.

Next, you need to prepare your assets to be sent:

Python
files = {
  'document': open('document.pdf', 'rb'),
  'company-logo': open('logo.png', 'rb')
}

The requests library expects a file object to be passed in. So, open your assets here.

Making the Request

Finally, you’re ready to make your request. Make sure to replace the your_api_key_here placeholder with your actual API key if it hasn’t been replaced yet:

Python
headers = {
  'Authorization': 'Bearer your_api_key_here'
}

response = requests.request(
  'POST',
  'https://api.pspdfkit.com/build',
  headers=headers,
  files=files,
  data=payload,
  stream=True
)

with open('result.pdf', 'wb') as fd:
  for chunk in response.iter_content(chunk_size=8096):
    fd.write(chunk)

This will make a request to PSPDFKit API, send your previously defined instructions object and your assets to the API, and save the resulting PDF as result.pdf in the same folder as your Python file.

And with that, you’re ready to make a request. Run python pspdfkit.py, and result.pdf should show up next to your Python file.

While this example made use of our watermarking API, this same approach can be used for all our available tools.

Full Code

For your convenience, here’s the whole code. Just copy it and run it:

Python
import requests
import json

instructions = {
  'parts': [
    {
      'file': 'document'
    }
  ],
  'actions': [
    {
      'type': 'watermark',
      'image': 'company-logo',
      'width': '50%'
    },
    {
      'type': 'watermark',
      'text': 'Property of PSPDFKit',
      'width': 150,
      'height': 20,
      'left': 0,
      'bottom': '100%'
    }
  ]
}

payload = {
  'instructions': json.dumps(instructions)
}

headers = {
  'Authorization': 'Bearer your_api_key_here'
}

files = {
  'document': open('document.pdf', 'rb'),
  'company-logo': open('logo.png', 'rb')
}

response = requests.request(
  'POST',
  'https://api.pspdfkit.com/build',
  headers=headers,
  files=files,
  data=payload,
  stream=True
)

with open('result.pdf', 'wb') as fd:
  for chunk in response.iter_content(chunk_size=8096):
    fd.write(chunk)