Sign PDF with Java

This guide will assist you in integrating DocuSeal document e-signing capabilities into your Java 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 Java

  • 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:

ET6sBznGN42bTMEaNMkzAa

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:

https://api.docuseal.co/submissions

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 Unirest library and core Java libraries:

import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;
import com.google.gson.Gson;
import java.util.HashMap;
import java.util.Map;

Map<String, Object> bodyMap = new HashMap<>();
bodyMap.put("template_id", 1000001);
bodyMap.put("send_email", true);
Map<String, String> submitter = new HashMap<>();
submitter.put("role", "First Party");
submitter.put("email", "john.doe@example.com");
bodyMap.put("submitters", new Map[]{submitter});

String jsonBody = new Gson().toJson(bodyMap);

HttpResponse<String> response = Unirest.post("https://api.docuseal.co/submissions")
  .header("X-Auth-Token", "API_KEY") // Replace with your API key
  .header("content-type", "application/json")
  .body(jsonBody)
  .asString();

System.out.println(response.getBody());

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">
      <DocusealForm
        src="https://docuseal.co/d/LEVGR9rhZYf86M" // Unique template URL
        onComplete={(data) => console.log(data)}
      />
    </div>
  );
}

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.

https://yourwebsite.com

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 the Spring Web library to handle the webhook payload and save the signed PDFs to the local file system.

import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.client.RestTemplate;
import org.springframework.core.io.Resource;
import org.springframework.core.io.ByteArrayResource;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.nio.file.Path;
import java.util.Map;

@RestController
public class WebhookController {

    @PostMapping("/webhook")
    public void handleWebhook(@RequestBody Map<String, Object> payload) {
        String eventType = (String) payload.get("event_type");
        if ("form.completed".equals(eventType)) {
            var data = (Map<String, Object>) payload.get("data");
            var documents = (List<Map<String, String>>) data.get("documents");
            if (documents != null) {
                for (var document : documents) {
                    String url = document.get("url");
                    String name = document.get("name").replaceAll("[^a-zA-Z0-9_\\-\\.]", "_") + ".pdf";
                    Path savePath = Paths.get("saved_files", name);

                    try {
                        RestTemplate restTemplate = new RestTemplate();
                        Resource resource = restTemplate.getForObject(url, ByteArrayResource.class);
                        if (resource != null) {
                            Files.createDirectories(savePath.getParent());
                            Files.write(savePath, resource.getByteArray());
                            System.out.println("Document saved to: " + savePath);
                        }
                    } catch (Exception e) {
                        e.printStackTrace();
                    }
                }
            }
        }
    }
}

Conclusions

In this guide, we have only covered the most basic example of using DocuSeal in a Java 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.