DocSpring Java SDK

The official Java client for the DocSpring API. DocSpring fills PDF templates with your data, generates PDFs from HTML templates, combines PDFs and collects e-signatures.

Documentation · API reference · Maven Central · Changelog

Version 3.3.0. Requires Java 8 or later.

Install and configure

Maven: add to your pom.xml dependencies:

<dependency>
  <groupId>com.docspring</groupId>
  <artifactId>DocSpring</artifactId>
  <version>3.3.0</version>
</dependency>

Gradle: add to your build.gradle:

implementation 'com.docspring:DocSpring:3.3.0'

Configure authentication via environment variables:

export DOCSPRING_TOKEN_ID="API_TOKEN_ID"
export DOCSPRING_TOKEN_SECRET="API_TOKEN_SECRET"

You can also configure the region or host. The host takes priority over the region:

export DOCSPRING_REGION="US" # US or EU (defaults to US)
export DOCSPRING_HOST="docspring.yourcompany.com" # For on-premise deployments

Initialize the client with no arguments:

com.docspring.Client api = new com.docspring.Client();

Or provide credentials directly:

com.docspring.Client api = new com.docspring.Client("API_TOKEN_ID", "API_TOKEN_SECRET");

Pass a host or region too. A null host or region falls back to its environment variable, and a host (including DOCSPRING_HOST) is used before a region:

com.docspring.Client api = new com.docspring.Client("API_TOKEN_ID", "API_TOKEN_SECRET", null, "EU");

Generate a PDF

Fill a template with data (use your template's ID in place of tpl_1234567890abcdef01):

String templateId = "tpl_1234567890abcdef01";
com.docspring.CreatePdfSubmissionData submission =
    new com.docspring.CreatePdfSubmissionData()
        .data(
            new java.util.HashMap<String, Object>() {
              {
                put("first_name", "John");
                put("last_name", "Smith");
                put("phone_number", "+11234567890");
              }
            })
        .metadata(
            new java.util.HashMap<String, Object>() {
              {
                put("foo", 123);
                put("bar", "baz");
              }
            });

try {
  Object result = api.generatePdf(templateId, submission, null);
  System.out.println(result);
} catch (com.docspring.ApiException ex) {
  System.out.println(ex);
} catch (Exception ex) {
  System.out.println(ex);
}

By default the call waits for the PDF, for up to 95 seconds, and the submission in the response has its download_url. Set wait to false to get a pending submission straight away. Sync vs. async processing covers the time limit, status checks and webhooks.

Methods

docs/Client.md has each method's parameters and return type, and docs/ has the models. The API reference has Java code for every method.

Method	Description
addFieldsToTemplate	Add new fields to a Template
batchGeneratePdfs	Generate multiple PDFs
combinePdfs	Merge submission PDFs, template PDFs, or custom files
copyTemplate	Copy a template
createCustomFileFromUpload	Create a new custom file from a cached S3 upload
createDataRequestEvent	Create a new event for emailing a signee a request for signature
createDataRequestToken	Create a new data request token for form authentication
createFolder	Create a folder
createHtmlTemplate	Create a new HTML template
createPdfTemplate	Create a new PDF template with a form POST file upload
createPdfTemplateFromUpload	Create a new PDF template from a cached S3 file upload
createWebhook	Create a webhook
deleteFolder	Delete a folder
deleteTemplate	Delete a template
deleteWebhook	Delete a webhook
expireCombinedSubmission	Expire a combined submission
expireSubmission	Expire a PDF submission
generatePdf	Generate a PDF
generatePreview	Generate a preview PDF for partially completed data requests
getCombinedSubmission	Check the status of a combined submission (merged PDFs)
getDataRequest	Look up a submission data request
getFullTemplate	Fetch the full attributes for a PDF template
getPresignUrl	Get a presigned S3 URL for direct file upload
getSubmission	Check the status of a PDF
getSubmissionBatch	Check the status of a submission batch job
getTemplate	Check the status of an uploaded template
getTemplateModelCode	Generate typed model code for a template
getTemplateSchema	Fetch the JSON schema for a template
getWebhook	Get a webhook
listCombinedSubmissions	Get a list of all combined submissions
listFolders	Get a list of all folders
listSubmissions	List all submissions
listTemplates	Get a list of all templates
listTemplateSubmissions	List all submissions for a given template
listWebhooks	Get a list of all webhooks
moveFolderToFolder	Move a folder
moveTemplateToFolder	Move Template to folder
publishTemplateVersion	Publish a template version
renameFolder	Rename a folder
restoreTemplateVersion	Restore a template version
testAuthentication	Test authentication
updateDataRequest	Update a submission data request
updateTemplate	Update a Template
updateTemplateDocument	Update a template's document with a form POST file upload
updateTemplateDocumentFromUpload	Update a template's document with a cached S3 file upload
updateWebhook	Update a webhook

Errors

Methods throw com.docspring.ApiException for an error response, with the HTTP status in getCode() and the body in getResponseBody().

API changes

DocSpring adds fields and enum values to API v1 without releasing a new API version. Changes that would break existing code, such as removing or renaming a field, go in a new API version (API changes). So this SDK keeps working with responses that are newer than it is:

• The model keeps a response field added to the API after this release in its additional properties (getAdditionalProperties()).
• An enum value added to the API after this release comes back as UNKNOWN_DEFAULT_OPEN_API, so give each switch over an enum a case or default for it.

Upgrade the SDK to read new fields and enum values. The changelog lists what each release adds.

About this SDK

This SDK is generated from DocSpring's OpenAPI spec with DocSpring's fork of OpenAPI Generator 7.16.0. The fork changes the Java generator:

• Enum values added to the API after this release come back as UNKNOWN_DEFAULT_OPEN_API for enums that can be null too. Stock OpenAPI Generator returns null for those.

On top of the generated code, we add:

• A client constructor that reads your credentials, region and host from the environment.

Because the code is generated, we can't merge pull requests that change it. Please open an issue or email support@docspring.com instead, and we'll fix it in the generator. AGENTS.md is a short guide for AI coding agents.

License

MIT. See LICENSE.