Sign PDF with Python

This guide will assist you in integrating DocuSeal document e-signing capabilities into your Python application. With DocuSeal, you can create document templates from your PDF files, send them to the signers, and receive signed copies. Templates can be created either using our web UI or through the API. For instance, you can design a document template with various field types using HTML and CSS or PDF upload. More information on this can be found in our guides.

How to sign PDFs with Python

  • Create a DocuSeal account and obtain an API key.
  • Create a document template using web UI or API.
  • Send a document signing request by specifying the template and information about the signers. Alternatively, embed a signing form on your website.
  • Manage signed documents in your DocuSeal account or utilize our webhooks for process automation.

Obtaining an Authorization Token

Before you begin making requests to our API, you need to obtain an authorization token so that we can identify you and your API requests.

To do this, you should register on our website if you haven't already and obtain an authorization token via Developer Console. The authorization token will look something like this:


Sending a Signing Request

DocuSeal allows you to sign a document by one or multiple signatories. Each signing request is referred to as a "submission", and each signatory is called a "submitter". Let's take a look at an example of sending a signing request to one signatory.

You can send signing requests using an HTTP POST request to the address:

In the request body, you should specify the following:

  • template_id - the template identifier
  • send_email - send email invitations for signing
  • submitters - an array of submitters

Each submitter should contain:

  • role - the role of the submitter
  • email - the email address of the submitter

Here's an example of how to create a submission using the http.client library:

import http.client
import json

conn = http.client.HTTPSConnection("")

data = {
  "template_id": 1000001,
  "send_email": True,
  "submitters": [
      "role": "First Party",
      "email": ""

payload = json.dumps(data)

headers = {
  'X-Auth-Token': "API_KEY", # Replace with your API key
  'content-type': "application/json"

conn.request("POST", "/submissions", payload, headers)

res = conn.getresponse()
data =


DocuSeal API has many other parameters that you can use for sending signing requests. In this guide, we will only cover the most basic example so you can understand how it works. For more detailed information, you can refer to our documentation.

Embedded Signing Form

In the previous example, we used the API to send a signing request, but sometimes you may not have the opportunity to use the API or the DocuSeal web UI. Also, you may not always know the email of the signer, but you do know that they have visited your website. In such cases, you can use an embedded Signing form. This allows you to embed a Signing form on your website so that the signer can sign the document directly on your website. To embed the Signing form, you need to create a document template in our web UI or using our API and use the unique template ID.

Let's integrate a signing form into our web page using React for this example (DocuSeal also provides libraries for Vue.js and plain JavaScript). To do this, install the @docuseal/react library. You can do this using yarn:

yarn add @docuseal/react

Or using npm:

npm install @docuseal/react
  • src - is a unique URL of the template, which you can obtain from the DocuSeal control panel after creating the template or by using the API.
  • onComplete - is a function that will be called after the document is successfully signed. It takes an object with the signed data.
import React from "react"
import { DocusealForm } from '@docuseal/react'

export function App() {
  return (
    <div className="app">
        src="" // Unique template URL
        onComplete={(data) => console.log(data)}

After adding this code to your page, you will see such a signing form on your website. However, you can customize its appearance and behavior using many parameters. You can read more about this in our documentation.

Processing Sign Results Using Webhooks

After the signer has signed the document, DocuSeal can send you the sign results using a webhook. You can use these results to process the sign in your application. For example, you can save the signed document in your application. To do this, you need to specify the address of your server, to which we will send the sign results. You can do this in the webhooks settings.

DocuSeal can send you 3 types of webhooks:

  • form.viewed - when the signer first views the Signing form
  • form.started - when the signer starts filling out the Signing form
  • form.completed - when all signers have completed filling out the Signing form

Let's consider an example when the signer has completed filling out the Signing form, and a webhook has been sent to your server. To do this, you need to create a webhook handler on your server that will process the sign results.

In this example, we use Flask to create a simple server that listens for incoming webhooks from DocuSeal and saves the signed documents to the local file system.

from flask import Flask, request, jsonify
import requests
import os

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def handle_webhook():
    data = request.json
    event_type = data.get('event_type')
    documents = data.get('data', {}).get('documents')

    if event_type == 'form.completed' and documents:
        for document in documents:
            response = requests.get(document['url'])
            save_path = os.path.join('saved_files', f"{document['name']}.pdf")

            os.makedirs(os.path.dirname(save_path), exist_ok=True)

            with open(save_path, 'wb') as file:
                print(f"Document saved to: {save_path}")

        return jsonify({"message": "Documents processed and saved"}), 200

    return jsonify({"error": "Invalid request"}), 400

if __name__ == '__main__':, debug=True)


In this guide, we have only covered the most basic example of using DocuSeal in a Python application. DocuSeal has many other capabilities that you can use to enhance your application. For example, you can embed not only the Signing form on your website but also the Form builder. You can also use the API to fully automate the process of generating custom documents using HTML and then sending them for signer without using the DocuSeal web UI. Additionally, you can host DocuSeal on your own server to gain the full ownership and control over your data.