Java Migration Guide

Migrating the Java SDK from `hellosign-java-sdk` to `dropbox-sign`

Welcome! Dropbox Sign's new Java SDK is generated from our officially maintained OpenAPI spec. In this release, we've made important updates that introduce new functionality and create feature parity between the Dropbox Sign API and the Java SDK. However, some of these changes are considered "breaking" in the sense that they'll require you to update your existing code in order to continue using the SDK.

In this migration guide, we'll cover core concepts in the new SDK, highlight differences from legacy versions, and provide example code showing how past implementations map to the new version's syntax. We'll link out to supporting documents that offer more context behind the breaking changes and why we made them. We apologize for any inconvenience these changes may cause, but are confident the new features will add value to your integration.

Remember that we are here to help if you have any questions or need assistance along the way. Thank you for using Dropbox Sign's Java SDK. We hope you enjoy the improvements!

Architecture and Tooling

As mentioned above, the new Java SDK (dropbox-sign) is generated from our OpenAPI Spec. Some of the architectural changes impact the tools and locations you use to interact with the SDK.

SDK Resources

Download -- using this new maven repo. New Java SDK versions will now be published here.
Development -- active development against the Java SDK happens here: hellosign-openapi/sdks/java.
SDK GitHub Repo -- dropbox-sign-java is updated based on changes to hellosign-openapi/sdks/java, but no active development work happens there.
Reference Docs -- the automatically generated Reference Docs are a great way to explore the SDK.
Examples -- our full suite of ready to use examples will help you get started quickly.
Engagement -- use the OpenAPI repo to submit Issues or Pull Requests for the Java SDK.

Core Concepts and Patterns

This section contains the core concepts and patterns of the new SDK and highlights differences from the legacy SDK.

Installation

The installation process remains the same as it was in the Legacy SDK, and can be completed by either utilizing either Maven or Gradle.

Using Maven (v2 with jakarta)Using Gradle (v2 with jakarta)Using Maven (v1 with javax)Using Gradle (v1 with javax)

Copy

Copied

<dependency>
  <groupId>com.dropbox.sign</groupId>
  <artifactId>dropbox-sign</artifactId>
  <version>2.x.x-</version>
</dependency>

Copy

Copied

repositories {
  mavenCentral()     // Needed if the 'dropbox-sign' jar has been published to maven central.
  mavenLocal()       // Needed if the 'dropbox-sign' jar has been published to the local maven repo.
}

dependencies {
   implementation "com.dropbox.sign:dropbox-sign:2.x.x"
}

Copy

Copied

<dependency>
  <groupId>com.dropbox.sign</groupId>
  <artifactId>dropbox-sign</artifactId>
  <version>1.x.x-</version>
</dependency>

Copy

Copied

repositories {
  mavenCentral()     // Needed if the 'dropbox-sign' jar has been published to maven central.
  mavenLocal()       // Needed if the 'dropbox-sign' jar has been published to the local maven repo.
}

dependencies {
   implementation "com.dropbox.sign:dropbox-sign:1.x.x"
}

Importing the SDK

Legacy SDK - NamespacesNew SDK - Namespaces

Copy

Copied

import com.hellosign.sdk;

Copy

Copied

import com.dropbox.sign.ApiClient;
import com.dropbox.sign.ApiException;
import com.dropbox.sign.Configuration;
import com.dropbox.sign.api.*;
import com.dropbox.sign.auth.*;
import com.dropbox.sign.model.*;

The New SDK organizes methods and classes across multiple namespaces; each with a specific purpose.

Namespace	Purpose
`com.dropbox.sign.api.*`	A collection of functions to interact with the API endpoints
`com.dropbox.sign.ApiClient`	A collection of classes that focus mainly on set-up, configuration, and exceptions
`com.dropbox.sign.model.*`	A collection of models for all endpoint classes and sub classes

Authentication

This section covers how to authenticate and configure your API Key or OAuth token when using the New SDK (dropbox-sign).

Legacy SDK (hellosign-java-sdk@5.2.3 and earlier): An instance of HelloSignClient had to be initialize with your API key (or OAuth Token).
New SDK (dropbox-sign): HelloSignClient no longer needs to be instantiated with your API Key. The API Key (or OAuth Token) can be set up by configuring an HTTP basic authorization.

Legacy SDK- Client API KeyNew SDK - Client API KeyLegacy SDK - Client Access TokenNew SDK - Client Access Token

Copy

Copied

HelloSignClient client = new HelloSignClient(apiKey);

Copy

Copied

import com.dropbox.sign.ApiException;
import com.dropbox.sign.Configuration;
import com.dropbox.sign.api.*;
import com.dropbox.sign.auth.*;
import com.dropbox.sign.model.*;

public class Example {
    public static void main(String[] args) {
        var apiClient = Configuration.getDefaultApiClient()
            .setApiKey("YOUR_API_KEY");
    }
}

Copy

Copied

HelloSignClient client = new HelloSignClient("SIGN_IN_AND_CREATE_API_KEY_FIRST");
String code = "1b0d28d90c86c141";
String clientId = "cc91c61d00f8bb2ece1428035716b";
String clientSecret = "1d14434088507ffa390e6f5528465";
client.getOauthData(code, clientId, clientSecret);

// Subsequent requests are made using the OAuth data retrieved above
SignatureRequestList list = client.getSignatureRequests();

Copy

Copied

import com.dropbox.sign.ApiException;
import com.dropbox.sign.Configuration;
import com.dropbox.sign.api.*;
import com.dropbox.sign.auth.*;
import com.dropbox.sign.model.*;

public class Example {
    public static void main(String[] args) {
        var apiClient = Configuration.getDefaultApiClient()
            .setBearerToken("YOUR_ACCESS_TOKEN");
    }
}

Endpoints Grouped into Classes

The new SDK divides endpoints across unique Classes:

Class Name and Reference	API Reference
AccountApi	/account/* Endpoints
ApiAppApi	/api_app/* Endpoints
BulkSendJobApi	/bulk_send_job/* Endpoints
EmbeddedApi	/embedded/* Endpoints
OAuthApi	/oauth/* Endpoints
ReportApi	/report/* Endpoints
SignatureRequestApi	/signature_request/* Endpoints
TeamApi	/team/* Endpoints
TemplateApi	/template/* Endpoints
UnclaimedDraftApi	/unclaimed_draft/* Endpoints

Using Models to Pass Parameters

Models are used to define the structure and value of the parameters being passed. The fully assembled model is passed to the API endpoint method.

New SDK Using Models to Pass Parameters

Copy

Copied

import com.dropbox.sign.ApiException;
import com.dropbox.sign.Configuration;
import com.dropbox.sign.api.*;
import com.dropbox.sign.auth.*;
import com.dropbox.sign.model.*;
import com.dropbox.sign.model.SubOAuth.ScopesEnum;

import java.io.File;
import java.util.Collections;
import java.util.List;

public class Example {
    public static void main(String[] args) {
        var apiClient = Configuration.getDefaultApiClient()
            .setApiKey("YOUR_API_KEY");

        var apiAppApi = new ApiAppApi(apiClient);

        var oauth = new SubOAuth()
            .callbackUrl("https://example.com/oauth")
            .scopes(List.of(ScopesEnum.BASIC_ACCOUNT_INFO, ScopesEnum.REQUEST_SIGNATURE));

        var whiteLabelingOptions = new SubWhiteLabelingOptions()
            .primaryButtonColor("#00b3e6")
            .primaryButtonTextColor("#ffffff");

        var customLogoFile = new File("CustomLogoFile.png");

        var data = new ApiAppCreateRequest()
            .name("My Production App")
            .domains(Collections.singletonList("example.com"))
            .oauth(oauth)
            .whiteLabelingOptions(whiteLabelingOptions)
            .customLogoFile(customLogoFile);

        try {
            ApiAppGetResponse result = apiAppApi.apiAppCreate(data);
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception when calling AccountApi#accountCreate");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Reason: " + e.getResponseBody());
            System.err.println("Response headers: " + e.getResponseHeaders());
            e.printStackTrace();
        }
    }
}

Path and Query Parameters

In the legacy SDK you would pass Path and Query parameters alongside any POST data to the API endpoint:

Legacy SDK - Path and Query Parameters

Copy

Copied

HelloSignClient client = new HelloSignClient("API_KEY");
String signatureRequestId = "fa5c8a0b0f492d768749333ad6fcc214c111e967";
String emailAddress = "john@example.com";
SignatureRequest request = client.requestEmailReminder(signatureRequestId, emailAddress);

The new SDK now requires POST data be an object when calling any API endpoint. Path and Query parameters must be passed individually to these methods.

New SDK - Path and Query Parameters

Copy

Copied

import com.dropbox.sign.ApiException;
import com.dropbox.sign.Configuration;
import com.dropbox.sign.api.*;
import com.dropbox.sign.auth.*;
import com.dropbox.sign.model.*;

public class Example {
    public static void main(String[] args) {
        var apiClient = Configuration.getDefaultApiClient()
            .setApiKey("YOUR_API_KEY");

        var signatureRequestApi = new SignatureRequestApi(apiClient);

        var signatureRequestId = "2f9781e1a8e2045224d808c153c2e1d3df6f8f2f";

        var data = new SignatureRequestRemindRequest()
            .emailAddress("john@example.com");

        try {
            SignatureRequestGetResponse result = signatureRequestApi.signatureRequestRemind(signatureRequestId, data);
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception when calling AccountApi#accountCreate");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Reason: " + e.getResponseBody());
            System.err.println("Response headers: " + e.getResponseHeaders());
            e.printStackTrace();
        }
    }
}

Error Handling and Warnings

The New SDK handles errors and warnings differently. See the table below for a breakdown of the changes:

Error Handling

Errors are an instance of com.dropbox.sign.ApiException with its getErrorResponse() method returning an instance of com.dropbox.sign.model.ErrorResponse class and should be handled using Try/Catch blocks.

Copy

Copied

import com.dropbox.sign.ApiException;
import com.dropbox.sign.Configuration;
import com.dropbox.sign.api.*;
import com.dropbox.sign.auth.*;
import com.dropbox.sign.model.*;

public class Example {
    public static void main(String[] args) {
        var apiClient = Configuration.getDefaultApiClient()
            .setApiKey("YOUR_API_KEY");

        var accountApi = new AccountApi(apiClient);

        try {
            AccountGetResponse result = accountApi.accountGet(null, "jack@example.com");
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception when calling AccountApi#accountCreate");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Reason: " + e.getResponseBody());
            System.err.println("Response headers: " + e.getResponseHeaders());
            e.printStackTrace();
        }
    }
}

Warnings

Warnings are a list of com.dropbox.sign.model.WarningResponse.

New SDK - Warnings

Copy

Copied

import com.dropbox.sign.ApiException;
import com.dropbox.sign.Configuration;
import com.dropbox.sign.api.*;
import com.dropbox.sign.auth.*;
import com.dropbox.sign.model.*;

import java.util.Objects;

public class Example {
    public static void main(String[] args) {
        var apiClient = Configuration.getDefaultApiClient()
            .setApiKey("YOUR_API_KEY");

        var accountApi = new AccountApi(apiClient);

        var data = new AccountCreateRequest()
            .emailAddress("newuser@dropboxsign.com");

        try {
            AccountCreateResponse result = accountApi.accountCreate(data);
            System.out.println(result);

            // warning loop
            Objects.requireNonNull(result.getWarnings()).forEach(warning -> {
                System.err.println("Warning Name: " + warning.getWarningName());
                System.err.println("Warning Message: " + warning.getWarningMsg());
            });
        } catch (ApiException e) {
            System.err.println("Exception when calling AccountApi#accountCreate");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Reason: " + e.getResponseBody());
            System.err.println("Response headers: " + e.getResponseHeaders());
            e.printStackTrace();
        }
    }
}

Instantiating Objects From Data

There are two ways to instantiate an object.

You can use new with setter methods
You can use the init() static method

New SDK - Using setter methodsNew SDK - Using init() Static Method

Copy

Copied

var signer1 = new SubSignatureRequestSigner()
    .emailAddress("jack@example.com")
    .name("Jack")
    .order(0);

var attachment1 = new SubAttachment()
    .name("Attachment 1")
    .instructions("Please download this file")
    .signerIndex(0)
    .required(true);

Copy

Copied

var signer1 = SubSignatureRequestSigner.init(
    new ObjectMapper().writeValueAsString(new HashMap<>()  {{
        put("email_address", "jack@example.com");
        put("name", "Jack");
        put("order", 0);
    }})
);

var attachment1 = SubAttachment.init(
    new ObjectMapper().writeValueAsString(new HashMap<>()  {{
        put("name", "Attachment 1");
        put("instructions", "Please download this file");
        put("signer_index", 0);
        put("required", true);
    }})
);

Note

init() creates a full object using all the data you pass, including nested data to instantiate nested objects. Any parameters that you do not pass data for will be set to their default value (including null).

Event Callback Helper

A callback helper class is included in the New SDK repo to assist in verifying callbacks. The helper simplifies:

Checking event authenticity with built in event hash check
Displaying event types (account callback vs. app callback)
Displaying event messages

The EventCallbackHelper and EventCallbackRequest classes facilitate parsing of event data and assist in validating that a callback originated from Dropbox Sign.We will send event callback payloads to you as a multipart/form-data request with a single json formfield that contains your event callback as a JSON string.

Example Event Callback Request From US to YOU

Copy

Copied

curl -X POST 'https://example.com/YOUR_EVENT_CALLBACK_URL' \
  -F 'json={"event":{"event_type":"account_confirmed","event_time":"1669926463","event_hash":"ff8b03439122f9160500c3fb855bdee5a9ccba5fff27d3b258745d8f3074832f","event_metadata":{"related_signature_id":null,"reported_for_account_id":"6421d70b9bd45059fa207d03ab8d1b96515b472c","reported_for_app_id":null,"event_message":null}}}'

Example JSON Payload

Copy

Copied

{
  "event": {
    "event_type": "account_confirmed",
    "event_time": "1669926463",
    "event_hash": "ff8b03439122f9160500c3fb855bdee5a9ccba5fff27d3b258745d8f3074832f",
    "event_metadata": {
      "related_signature_id": null,
      "reported_for_account_id": "6421d70b9bd45059fa207d03ab8d1b96515b472c",
      "reported_for_app_id": null,
      "event_message": null
    }
  }
}

How to use the EventCallbackHelper

Copy

Copied

import com.dropbox.sign.EventCallbackHelper;
import com.dropbox.sign.model.EventCallbackRequest;

public class Example {
    public static void main(String[] args) throws Exception {
        // use your API key
        var apiKey = "324e3b0840f065eb51f3fd63231d0d33daa35d4ed10d27718839e81737065782";

        // callbackData represents data we send to you
        var callbackData  = request.getParameter("json");

        var callbackEvent = EventCallbackRequest.init(callbackData);

        // verify that a callback came from HelloSign.com
        if (EventCallbackHelper.isValid(apiKey, callbackEvent)) {
            // one of "account_callback" or "api_app_callback"
            var callbackType = EventCallbackHelper.getCallbackType(callbackEvent);

            // do your magic below!
        }
    }
}

Differences from Legacy SDK

This section highlights larger changes to be aware of when migrating to the new SDK.

Form Fields per Document

The Form Fields per Document parameter has changed from a two dimensional array, to a one dimensional array—allowing you to designate which file you to add the field to using document_index. You can learn more about this change here: Form Fields per Document.

Legacy SDK - Form Fields Per DocumentNew SDK - Form Fields per Document

Copy

Copied

FormField signature1 = new FormField();
field.setX(100);
field.setY(100);
field.setType(FieldType.valueOf("signature"));
field.setSigner(1);
field.setPage(1);
field.setApiId("1234");
field.setHeight(10);
field.setWidth(20);
field.setIsRequired(true);
SignatureRequest request = new SignatureRequest();
Document doc = new Document();
doc.addFormField(signature1);

Copy

Copied

import com.dropbox.sign.ApiException;
import com.dropbox.sign.Configuration;
import com.dropbox.sign.api.*;
import com.dropbox.sign.auth.*;
import com.dropbox.sign.model.*;

public class Main {
    public static void main(String[] args) {
        var apiClient = Configuration.getDefaultApiClient()
            .setApiKey("YOUR_API_KEY");

        var signatureRequestApi = new SignatureRequestApi(apiClient);

        var signer1 = new SubSignatureRequestSigner()
            .emailAddress("jack@example.com")
            .name("Jack")
            .order(0);

        var formField1 = new SubFormFieldsPerDocumentText();
        formField1.documentIndex(0);
        formField1.apiId("134asdf");
        formField1.required(true);
        formField1.signer(0);
        formField1.width(100);
        formField1.height(16);
        formField1.x(112);
        formField1.y(700);
        formField1.page(1);
        formField1.placeholder("Full Name");
        formField1.validationType(SubFormFieldsPerDocumentText.ValidationTypeEnum.LETTERS_ONLY);

        var formField2 = new SubFormFieldsPerDocumentTextMerge();
        formField2.documentIndex(0);
        formField2.apiId("5678yuio");
        formField2.name("Address");
        formField2.required(true);
        formField2.signer(0);
        formField2.width(100);
        formField2.height(16);
        formField2.x(222);
        formField2.y(700);
        formField2.page(1);

        var formField3 = new SubFormFieldsPerDocumentSignature();
        formField3.documentIndex(0);
        formField3.apiId("zxcvuip");
        formField3.required(true);
        formField3.signer(1);
        formField3.width(150);
        formField3.height(30);
        formField3.x(400);
        formField3.y(715);
        formField3.page(2);

        var data = new SignatureRequestSendRequest()
            .title("NDA with Acme Co.")
            .subject("The NDA we talked about")
            .message("Please sign this NDA and then we can discuss more. Let me know if you have any questions.")
            .addFileUrlsItem("https://app.hellosign.com/docs/example_signature_request.pdf")
            .addSignersItem(signer1)
            .addFormFieldsPerDocumentItem(formField1)
            .addFormFieldsPerDocumentItem(formField2)
            .addFormFieldsPerDocumentItem(formField3);

        try {
            SignatureRequestGetResponse result = signatureRequestApi.signatureRequestSend(data);
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception when calling AccountApi#accountCreate");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Reason: " + e.getResponseBody());
            System.err.println("Response headers: " + e.getResponseHeaders());
            e.printStackTrace();
        }
    }
}

Instantiating the Correct Field Class

There are several different types of form fields you can define, identified by the value of the type field and a few ways to instantiate the correct object when making an API request.

The different classes for each type are:

Field Type	Class
checkbox	SubFormFieldsPerDocumentCheckbox
checkbox-merge	SubFormFieldsPerDocumentCheckboxMerge
date_signed	SubFormFieldsPerDocumentDateSigned
dropdown	SubFormFieldsPerDocumentDropdown
hyperlink	SubFormFieldsPerDocumentHyperlink
initials	SubFormFieldsPerDocumentInitials
radio	SubFormFieldsPerDocumentRadio
signature	SubFormFieldsPerDocumentSignature
text	SubFormFieldsPerDocumentText
text-merge	SubFormFieldsPerDocumentTextMerge

You can use ::init() on the base request class

Copy

Copied

var data = SignatureRequestSendRequest.init(new HashMap<>()  {{
    put("title", "NDA with Acme Co.");
    put("subject", "The NDA we talked about");
    put("message", "Please sign this NDA and then we can discuss more.");
    put("signers", List.of(
        new HashMap<>()  {{
            put("email_address", "jill@example.com");
            put("name", "Jill");
            put("order", 1);
        }}
    ));
    put("form_fields_per_document", List.of(
        new HashMap<>()  {{
            put("type", "signature");
            put("document_index", 0);
            put("api_id", "4688957689");
            put("name", "signature1");
            put("x", 5);
            put("y", 7);
            put("width", 60);
            put("height", 30);
            put("required", true);
            put("signer", 0);
            put("page", 1);
        }}
    ));
}});

You can use ::init() on the field class

Copy

Copied

var formField1 = SubFormFieldsPerDocumentSignature.init(new HashMap<>()  {{
    put("document_index", 0);
    put("api_id", "4688957689");
    put("name", "signature1");
    put("x", 5);
    put("y", 7);
    put("width", 60);
    put("height", 30);
    put("required", true);
    put("signer", 0);
    put("page", 1);
}});

var data = new SignatureRequestSendRequest();
data.addFormFieldsPerDocumentItem(formField1);

You can instantiate the class directly

Copy

Copied

var formField1 = new SubFormFieldsPerDocumentSignature();
formField1.setDocumentIndex(0);
formField1.setApiId("4688957689");
formField1.setName("signature1");
formField1.setX(5);
formField1.setY(7);
formField1.setWidth(60);
formField1.setHeight(30);
formField1.setRequired(true);
formField1.setSigner(0);
formField1.setPage(1);

Form Fields per Document Examples using the new SDK:

SignatureInitialsDate SignedTextText MergeCheckboxCheckbox MergeDropdownHyperlinkRadio

Copy

Copied

var formField1 = SubFormFieldsPerDocumentSignature.init(new HashMap<>()  {{
    put("document_index", 0);
    put("api_id", "4688957689");
    put("name", "signature1");
    put("x", 5);
    put("y", 7);
    put("width", 60);
    put("height", 30);
    put("required", true);
    put("signer", 0);
    put("page", 1);
}});

Copy

Copied

var formField1 = SubFormFieldsPerDocumentInitials.init(new HashMap<>()  {{
    put("document_index", 0);
    put("api_id", "4688957689");
    put("name", "initials1");
    put("x", 5);
    put("y", 7);
    put("width", 60);
    put("height", 30);
    put("required", true);
    put("signer", 0);
    put("page", 1);
}});

Copy

Copied

var formField1 = SubFormFieldsPerDocumentDateSigned.init(new HashMap<>()  {{
    put("document_index", 0);
    put("api_id", "4688957689");
    put("name", "date_signed1");
    put("x", 5);
    put("y", 7);
    put("width", 60);
    put("height", 30);
    put("required", true);
    put("signer", 0);
    put("page", 1);
}});

Copy

Copied

var formField1 = SubFormFieldsPerDocumentText.init(new HashMap<>()  {{
    put("document_index", 0);
    put("api_id", "4688957689");
    put("name", "text1");
    put("x", 5);
    put("y", 7);
    put("width", 60);
    put("height", 30);
    put("required", true);
    put("signer", 0);
    put("page", 1);
}});

Copy

Copied

var firstName = SubCustomField.init(new HashMap<>()  {{
    put("name", "first_name");
    put("value", "John");
}});

var formField1 = SubFormFieldsPerDocumentTextMerge.init(new HashMap<>()  {{
    put("document_index", 0);
    put("api_id", "4688957689");
    put("name", "first_name");
    put("x", 5);
    put("y", 7);
    put("width", 60);
    put("height", 30);
    put("required", true);
    put("signer", 0);
    put("page", 1);
}});

Copy

Copied

var formField1 = SubFormFieldsPerDocumentCheckbox.init(new HashMap<>()  {{
    put("document_index", 0);
    put("api_id", "4688957689");
    put("name", "checkbox1");
    put("x", 5);
    put("y", 7);
    put("width", 60);
    put("height", 30);
    put("required", true);
    put("signer", 0);
    put("page", 1);
}});

Copy

Copied

var isRegistered = SubCustomField.init(new HashMap<>()  {{
    put("name", "is_registered");
    put("value", "1");
}});

var formField1 = SubFormFieldsPerDocumentCheckboxMerge.init(new HashMap<>()  {{
    put("document_index", 0);
    put("api_id", "4688957689");
    put("name", "is_registered");
    put("x", 5);
    put("y", 7);
    put("width", 60);
    put("height", 30);
    put("required", true);
    put("signer", 0);
    put("page", 1);
}});

Copy

Copied

var formField1 = SubFormFieldsPerDocumentDropdown.init(new HashMap<>()  {{
    put("document_index", 0);
    put("api_id", "4688957689");
    put("name", "dropdown1");
    put("x", 5);
    put("y", 7);
    put("width", 60);
    put("height", 30);
    put("required", true);
    put("signer", 0);
    put("page", 1);
    put("options", List.of("Option 1","Option 2"));
    put("content", "Option 2");
}});

Copy

Copied

var formField1 = SubFormFieldsPerDocumentHyperlink.init(new HashMap<>()  {{
    put("document_index", 0);
    put("api_id", "4688957689");
    put("name", "hyperlink1");
    put("x", 5);
    put("y", 7);
    put("width", 60);
    put("height", 30);
    put("required", true);
    put("signer", "me_now");
    put("page", 1);
    put("content", "Click me!");
    put("content_url", "http://example.com");
}});

Copy

Copied

var formField1 = SubFormFieldsPerDocumentRadio.init(new HashMap<>()  {{
    put("document_index", 0);
    put("api_id", "4688957689");
    put("name", "radio1");
    put("x", 5);
    put("y", 7);
    put("width", 60);
    put("height", 30);
    put("required", true);
    put("signer", 0);
    put("page", 1);
    put("group", "RadioItemGroup1");
    put("is_checked", true);
}});

var formField2 = SubFormFieldsPerDocumentRadio.init(new HashMap<>()  {{
    put("document_index", 0);
    put("api_id", "46876587");
    put("name", "radio2");
    put("x", 5);
    put("y", 50);
    put("width", 60);
    put("height", 30);
    put("required", true);
    put("signer", 0);
    put("page", 1);
    put("group", "RadioItemGroup1");
    put("is_checked", false);
}});

var formFieldGroup1 = SubFormFieldGroup.init(new HashMap<>()  {{
    put("group_id", "RadioItemGroup1");
    put("group_label", "Radio Item Group 1");
    put("requirement", "require_0-1");
}});

"role" Value in `signers` Object

In the Legacy SDK when making a Signature Request using a Template the signers property was an object with the role name as the key. In the new SDK the role value has been moved into the signer object itself.For example for the /signature_request/send_with_template endpoint the signers property could be represented as:

Legacy SDK - signers with RolesNew SDK - signers with Roles

Copy

Copied

{
  "signers": {
    "Client": {
      "name": "George",
      "email_address": "george@example.com"
    },
    "Manager": {
      "name": "Bob",
      "email_address": "bob@example.com"
    }
  }
}

Copy

Copied

{
  "signers": [
    {
      "role": "Client",
      "name": "George",
      "email_address": "george@example.com"
    },
    {
      "role": "Manager",
      "name": "Bob",
      "email_address": "bob@example.com"
    }
  ]
}

Using the new SDK you would now send this data as follows:

New SDK - signers with Roles Example #1New SDK - signers with Roles Example #2

Copy

Copied

import com.dropbox.sign.ApiException;
import com.dropbox.sign.Configuration;
import com.dropbox.sign.api.*;
import com.dropbox.sign.auth.*;
import com.dropbox.sign.model.*;

import java.util.HashMap;
import java.util.List;

public class Example {
    public static void main(String[] args) throws Exception {
        var apiClient = Configuration.getDefaultApiClient()
            .setApiKey("YOUR_API_KEY");

        var signatureRequestApi = new SignatureRequestApi(apiClient);

        var data = new SignatureRequestSendWithTemplateRequest()
            .templateIds(List.of("c26b8a16784a872da37ea946b9ddec7c1e11dff6"))
            .subject("Purchase Order")
            .message("Glad we could come to an agreement.")
            .signers(List.of(
                SubSignatureRequestTemplateSigner.init(new HashMap<>()  {{
                    put("role", "Client");
                    put("name", "George");
                    put("email_address", "george@example.com");
                }}),
                SubSignatureRequestTemplateSigner.init(new HashMap<>()  {{
                    put("role", "Manager");
                    put("name", "Bob");
                    put("email_address", "bob@example.com");
                }})
            ));

        try {
            SignatureRequestGetResponse result = signatureRequestApi.signatureRequestSendWithTemplate(data);
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception when calling AccountApi#accountCreate");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Reason: " + e.getResponseBody());
            System.err.println("Response headers: " + e.getResponseHeaders());
            e.printStackTrace();
        }
    }
}

Copy

Copied

import com.dropbox.sign.ApiException;
import com.dropbox.sign.Configuration;
import com.dropbox.sign.api.*;
import com.dropbox.sign.auth.*;
import com.dropbox.sign.model.*;

import java.util.List;

public class Example {
    public static void main(String[] args) {
        var apiClient = Configuration.getDefaultApiClient()
            .setApiKey("YOUR_API_KEY");

        var signatureRequestApi = new SignatureRequestApi(apiClient);

        var signer1 = new SubSignatureRequestTemplateSigner()
            .role("Client")
            .name("George")
            .emailAddress("george@example.com");

        var signer2 = new SubSignatureRequestTemplateSigner()
            .role("Manager")
            .name("Bob")
            .emailAddress("bob@example.com");

        var data = new SignatureRequestSendWithTemplateRequest()
            .templateIds(List.of("c26b8a16784a872da37ea946b9ddec7c1e11dff6"))
            .subject("Purchase Order")
            .message("Glad we could come to an agreement.")
            .signers(List.of(signer1, signer2));

        try {
            SignatureRequestGetResponse result = signatureRequestApi.signatureRequestSendWithTemplate(data);
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception when calling AccountApi#accountCreate");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Reason: " + e.getResponseBody());
            System.err.println("Response headers: " + e.getResponseHeaders());
            e.printStackTrace();
        }
    }
}

"role" Value in `ccs` Property

In the Legacy SDK when making a Signature Request using a Template the ccs property was an object with the role name as the key. In the new SDK the role value has been moved into the cc object itself, alongside a new email_address property.For example for the /signature_request/send_with_template endpoint the ccs property could be represented as:

Legacy SDK - ccsNew SDK - ccs

Copy

Copied

{
  "ccs": {
    "Client": "george@example.com",
    "Manager": "bob@example.com"
  }
}

Copy

Copied

{
  "ccs": [
    {
      "role": "Client",
      "email_address": "george@example.com"
    },
    {
      "role": "Manager",
      "email_address": "bob@example.com"
    }
  ]
}

Using the new SDK you would now send this data as follows:

New SDK - ccs Example #1New SDK - ccs Example #2

Copy

Copied

import com.dropbox.sign.ApiException;
import com.dropbox.sign.Configuration;
import com.dropbox.sign.api.*;
import com.dropbox.sign.auth.*;
import com.dropbox.sign.model.*;

import java.util.HashMap;
import java.util.List;

public class Example {
    public static void main(String[] args) throws Exception {
        var apiClient = Configuration.getDefaultApiClient()
            .setApiKey("YOUR_API_KEY");

        var signatureRequestApi = new SignatureRequestApi(apiClient);

        var data = new SignatureRequestSendWithTemplateRequest()
            .templateIds(List.of("c26b8a16784a872da37ea946b9ddec7c1e11dff6"))
            .subject("Purchase Order")
            .message("Glad we could come to an agreement.")
            .signers(List.of(
                SubSignatureRequestTemplateSigner.init(new HashMap<>()  {{
                    put("role", "Client");
                    put("name", "George");
                    put("email_address", "george@example.com");
                }}),
                SubSignatureRequestTemplateSigner.init(new HashMap<>()  {{
                    put("role", "Manager");
                    put("name", "Bob");
                    put("email_address", "bob@example.com");
                }})
            ))
            .ccs(List.of(
                SubCC.init(new HashMap<>()  {{
                    put("role", "Client");
                    put("email_address", "george@example.com");
                }}),
                SubCC.init(new HashMap<>()  {{
                    put("role", "Manager");
                    put("email_address", "bob@example.com");
                }})
            ));

        try {
            SignatureRequestGetResponse result = signatureRequestApi.signatureRequestSendWithTemplate(data);
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception when calling AccountApi#accountCreate");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Reason: " + e.getResponseBody());
            System.err.println("Response headers: " + e.getResponseHeaders());
            e.printStackTrace();
        }
    }
}

Copy

Copied

import com.dropbox.sign.ApiException;
import com.dropbox.sign.Configuration;
import com.dropbox.sign.api.*;
import com.dropbox.sign.auth.*;
import com.dropbox.sign.model.*;

import java.util.List;

public class Example {
    public static void main(String[] args) {
        var apiClient = Configuration.getDefaultApiClient()
            .setApiKey("YOUR_API_KEY");

        var signatureRequestApi = new SignatureRequestApi(apiClient);

        var signer1 = new SubSignatureRequestTemplateSigner()
            .role("Client")
            .name("George")
            .emailAddress("george@example.com");

        var signer2 = new SubSignatureRequestTemplateSigner()
            .role("Manager")
            .name("Bob")
            .emailAddress("bob@example.com");

        var cc1 = new SubCC()
            .role("Manager")
            .emailAddress("george@example.com");

        var cc2 = new SubCC()
            .role("Client")
            .emailAddress("bob@example.com");

        var data = new SignatureRequestSendWithTemplateRequest()
            .templateIds(List.of("c26b8a16784a872da37ea946b9ddec7c1e11dff6"))
            .subject("Purchase Order")
            .message("Glad we could come to an agreement.")
            .signers(List.of(signer1, signer2))
            .ccs(List.of(cc1, cc2));

        try {
            SignatureRequestGetResponse result = signatureRequestApi.signatureRequestSendWithTemplate(data);
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception when calling AccountApi#accountCreate");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Reason: " + e.getResponseBody());
            System.err.println("Response headers: " + e.getResponseHeaders());
            e.printStackTrace();
        }
    }
}

"name" Value in `custom_fields` Property

In the Legacy SDK when making a Signature Request with the custom_fields property it was an object with the name as the key. In the new SDK the name value has been moved into the custom_field object itself.For example for the /signature_request/send_with_template endpoint the custom_fields property could be represented as:

Legacy SDK - custom_fieldsNew SDK - custom_fields

Copy

Copied

{
  "custom_fields": {
    "company": {
      "value": "ABC Corp",
      "required": true
    }
  }
}

Copy

Copied

{
  "custom_fields": [
    {
      "name": "company",
      "value": "ABC Corp",
      "required": true
    }
  ]
}

Using the new SDK you would now send this data as follows:

New SDK - custom_fields Example #1New SDK - custom_fields Example #2

Copy

Copied

import com.dropbox.sign.ApiException;
import com.dropbox.sign.Configuration;
import com.dropbox.sign.api.*;
import com.dropbox.sign.auth.*;
import com.dropbox.sign.model.*;

import java.util.HashMap;
import java.util.List;

public class Example {
    public static void main(String[] args) throws Exception {
        var apiClient = Configuration.getDefaultApiClient()
            .setApiKey("YOUR_API_KEY");

        var signatureRequestApi = new SignatureRequestApi(apiClient);

        var data = new SignatureRequestSendWithTemplateRequest()
            .templateIds(List.of("c26b8a16784a872da37ea946b9ddec7c1e11dff6"))
            .subject("Purchase Order")
            .message("Glad we could come to an agreement.")
            .signers(List.of(
                SubSignatureRequestTemplateSigner.init(new HashMap<>()  {{
                    put("role", "Client");
                    put("name", "George");
                    put("email_address", "george@example.com");
                }}),
                SubSignatureRequestTemplateSigner.init(new HashMap<>()  {{
                    put("role", "Manager");
                    put("name", "Bob");
                    put("email_address", "bob@example.com");
                }})
            ))
            .customFields(List.of(
                SubCustomField.init(new HashMap<>()  {{
                    put("name", "company");
                    put("value", "ABC Corp");
                    put("required", true);
                }})
            ));

        try {
            SignatureRequestGetResponse result = signatureRequestApi.signatureRequestSendWithTemplate(data);
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception when calling AccountApi#accountCreate");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Reason: " + e.getResponseBody());
            System.err.println("Response headers: " + e.getResponseHeaders());
            e.printStackTrace();
        }
    }
}

Copy

Copied

import com.dropbox.sign.ApiException;
import com.dropbox.sign.Configuration;
import com.dropbox.sign.api.*;
import com.dropbox.sign.auth.*;
import com.dropbox.sign.model.*;

import java.util.List;

public class Example {
    public static void main(String[] args) {
        var apiClient = Configuration.getDefaultApiClient()
            .setApiKey("YOUR_API_KEY");

        var signatureRequestApi = new SignatureRequestApi(apiClient);

        var signer1 = new SubSignatureRequestTemplateSigner()
            .role("Client")
            .name("George")
            .emailAddress("george@example.com");

        var signer2 = new SubSignatureRequestTemplateSigner()
            .role("Manager")
            .name("Bob")
            .emailAddress("bob@example.com");

        var customField1 = new SubCustomField()
            .name("company")
            .value("ABC Corp")
            .required(true);

        var data = new SignatureRequestSendWithTemplateRequest()
            .templateIds(List.of("c26b8a16784a872da37ea946b9ddec7c1e11dff6"))
            .subject("Purchase Order")
            .message("Glad we could come to an agreement.")
            .signers(List.of(signer1, signer2))
            .customFields(List.of(customField1));

        try {
            SignatureRequestGetResponse result = signatureRequestApi.signatureRequestSendWithTemplate(data);
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception when calling AccountApi#accountCreate");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Reason: " + e.getResponseBody());
            System.err.println("Response headers: " + e.getResponseHeaders());
            e.printStackTrace();
        }
    }
}

`template_id` to `template_ids`

The template_id parameter has been removed. You must now use template_ids.

Legacy SDK version	New SDK Version
Template ID (`template_id`) is passed as a singular string: `template_id : "1234567890"`	Template ID is passed as an array of strings (`template_ids`): `template_ids:["1234567890"]`

`file` to `files`

The file parameter has been renamed to files. Usage remains the same.Use .files([...]);

`file_url` to `file_urls`

The file_url parameter has been renamed to file_urls. Usage remains the same.Use .fileUrls([...]);

Interacting with Files

The new SDK version introduces some new patterns around uploading and downloading files. You can read about them more in depth here: Interacting with Files.

Uploading Files

Legacy SDK (hellosign-java-sdk@5.2.3 and earlier): Files could be uploaded via the Document Class.
New SDK (dropbox-sign): The Document Class has been removed. The three methods to upload files via the New SDK and their examples are:
addFilesItem method
file method
setFile method

Legacy SDK - Adding FilesNew SDK - addFilesItem methodNew SDK - files method

Copy

Copied

//Using the Document Class
Document doc1 = new Document();
doc1.setFile(new File("/NDA.pdf"));

Copy

Copied

SignatureRequestSendRequest data = new SignatureRequestSendRequest()
    .title("NDA with Acme Co.")
    .subject("The NDA we talked about")
    .message("Please sign this NDA")
    .signers(List.of(signer1, signer2))
    .addFilesItem(new File("/Documents/NDA.pdf"))

Copy

Copied

// This method accepts an Array of Files
var file1 = new File("Documents/NDA.pdf");
var file2 = new File("Documents/NDA2.pdf");

var data = new SignatureRequestSendRequest()
    .title("NDA with Acme Co.")
    .subject("The NDA we talked about")
    .message("Please sign this NDA")
    .signers(List.of(signer1, signer2))
    .files(List.of(file1, file2));

Copy

Copied

// This method accepts an Array of Files

var file1 = new File("Documents/NDA.pdf");
var file2 = new File("Documents/NDA2.pdf");

var data = new SignatureRequestSendWithTemplateRequest()
    .templateIds(List.of("b7fee29dd746ebab9d8cdfcb7cdbdd0c5a2bc67a"))
    .subject("Purchase Order")
    .message("Glad we could come to an agreement.")
    .signers(List.of(signer1))
    .ccs(List.of(cc1))
    .customFields(List.of(customField1))
    .signingOptions(signingOptions)
    .testMode(true);
data.setFiles(List.of(file1, file2));

All methods above utilize the built-in java.io.File Class to handle files.

Using the set File method

Because the setFile method return type is void, this method must be chained together with the Object, as shown on the example above.

Downloading Files

We now provide three different options to download files, for either signature requests and template files. Different endpoints provide the following options:

Return files as PDF or ZIP
Return a URL to the file (PDF only)
Return a data_uri base64 encoded file (PDFs only)

Examples for each endpoint in the New SDK (dropbox-sign) can be found in the table below:

Signature Request Files	Template Files
Download files as .pdf/zip	Download template files as .pdf/zip
Download files as file_url	Download template files as file_url
Download files as data_url	Download template files as data_url

New SDK - Download FilesNew SDK - Download as Data UriNew SDK - File File Url

Copy

Copied

import com.dropbox.sign.ApiException;
import com.dropbox.sign.Configuration;
import com.dropbox.sign.api.*;
import com.dropbox.sign.auth.*;

import java.io.File;

public class Example {
    public static void main(String[] args) {
        var apiClient = Configuration.getDefaultApiClient()
            .setApiKey("YOUR_API_KEY");

        var signatureRequestApi = new SignatureRequestApi(apiClient);

        var signatureRequestId = "fa5c8a0b0f492d768749333ad6fcc214c111e967";

        try {
            File result = signatureRequestApi.signatureRequestFiles(signatureRequestId, "pdf");
            result.renameTo(new File("file_response.pdf"));
        } catch (ApiException e) {
            System.err.println("Exception when calling AccountApi#accountCreate");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Reason: " + e.getResponseBody());
            System.err.println("Response headers: " + e.getResponseHeaders());
            e.printStackTrace();
        }
    }
}

Copy

Copied

import com.dropbox.sign.ApiException;
import com.dropbox.sign.Configuration;
import com.dropbox.sign.api.*;
import com.dropbox.sign.auth.*;
import com.dropbox.sign.model.*;

public class Example {
    public static void main(String[] args) {
        var apiClient = Configuration.getDefaultApiClient()
            .setApiKey("YOUR_API_KEY");

        var signatureRequestApi = new SignatureRequestApi(apiClient);

        var signatureRequestId = "fa5c8a0b0f492d768749333ad6fcc214c111e967";

        try {
            FileResponseDataUri result = signatureRequestApi.signatureRequestFilesAsDataUri(signatureRequestId);
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception when calling AccountApi#accountCreate");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Reason: " + e.getResponseBody());
            System.err.println("Response headers: " + e.getResponseHeaders());
            e.printStackTrace();
        }
    }
}

Copy

Copied

import com.dropbox.sign.ApiException;
import com.dropbox.sign.Configuration;
import com.dropbox.sign.api.*;
import com.dropbox.sign.auth.*;
import com.dropbox.sign.model.*;

public class Example {
    public static void main(String[] args) {
        var apiClient = Configuration.getDefaultApiClient()
            .setApiKey("YOUR_API_KEY");

        var signatureRequestApi = new SignatureRequestApi(apiClient);

        var signatureRequestId = "fa5c8a0b0f492d768749333ad6fcc214c111e967";

        try {
            FileResponse result = signatureRequestApi.signatureRequestFilesAsFileUrl(signatureRequestId);
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception when calling AccountApi#accountCreate");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Reason: " + e.getResponseBody());
            System.err.println("Response headers: " + e.getResponseHeaders());
            e.printStackTrace();
        }
    }
}

Downloading Templates

New SDK - Download Template FilesNew SDK - Template File as Data UriNew SDK - Template File as File Url

Copy

Copied

import com.dropbox.sign.ApiException;
import com.dropbox.sign.Configuration;
import com.dropbox.sign.api.*;
import com.dropbox.sign.auth.*;

import java.io.File;

public class Example {
    public static void main(String[] args) {
        var apiClient = Configuration.getDefaultApiClient()
            .setApiKey("YOUR_API_KEY");

        var templateApi = new TemplateApi(apiClient);

        var templateId = "f57db65d3f933b5316d398057a36176831451a35";

        try {
            File result = templateApi.templateFiles(templateId, "pdf");
            result.renameTo(new File("file_response.pdf"));
        } catch (ApiException e) {
            System.err.println("Exception when calling AccountApi#accountCreate");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Reason: " + e.getResponseBody());
            System.err.println("Response headers: " + e.getResponseHeaders());
            e.printStackTrace();
        }
    }
}

Copy

Copied

import com.dropbox.sign.ApiException;
import com.dropbox.sign.Configuration;
import com.dropbox.sign.api.*;
import com.dropbox.sign.auth.*;
import com.dropbox.sign.model.*;

public class Example {
    public static void main(String[] args) {
        var apiClient = Configuration.getDefaultApiClient()
            .setApiKey("YOUR_API_KEY");

        var templateApi = new TemplateApi(apiClient);

        var templateId = "f57db65d3f933b5316d398057a36176831451a35";

        try {
            FileResponseDataUri result = templateApi.templateFilesAsDataUri(templateId);
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception when calling AccountApi#accountCreate");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Reason: " + e.getResponseBody());
            System.err.println("Response headers: " + e.getResponseHeaders());
            e.printStackTrace();
        }
    }
}

Copy

Copied

import com.dropbox.sign.ApiException;
import com.dropbox.sign.Configuration;
import com.dropbox.sign.api.*;
import com.dropbox.sign.auth.*;
import com.dropbox.sign.model.*;

public class Example {
    public static void main(String[] args) {
        var apiClient = Configuration.getDefaultApiClient()
            .setApiKey("YOUR_API_KEY");

        var templateApi = new TemplateApi(apiClient);

        var templateId = "f57db65d3f933b5316d398057a36176831451a35";

        try {
            FileResponse result = templateApi.templateFilesAsFileUrl(templateId, "pdf", false, false);
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception when calling AccountApi#accountCreate");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Reason: " + e.getResponseBody());
            System.err.println("Response headers: " + e.getResponseHeaders());
            e.printStackTrace();
        }
    }
}

Endpoint mapping

This section shows you how endpoints in the legacy SDK map to the new SDK. It doesn't cover all endpoints, but gives you an idea of mapping implementations between the two SDKs. Please reach out if you think we're missing an important example.

Send Non-Embedded Signature Request
Create Embedded Signature Request
Send Non-Embedded Signature Request with Template
Download Files
Get Signature Request
List Signature Request
Create Embedded Unclaimed Draft
Create Embedded Template- with Merge Fields
Create API App - with WhiteLabelingOptions

Send Non-Embedded Signature Request

Legacy SDK - Non-Embedded SignatureNew SDK - Non-Embedded Signature

Copy

Copied

SignatureRequest request = new SignatureRequest();
request.setSubject("NDA");
request.setMessage("Hi Jack, Please sign this NDA and let's discuss.");
request.addSigner("jack@example.com", "Jack");
request.addFile(new File("path_to/myfile.pdf"));
SignatureRequest response = client.sendSignatureRequest(request);
System.out.println(response.toString());

Copy

Copied

import com.dropbox.sign.ApiException;
import com.dropbox.sign.Configuration;
import com.dropbox.sign.api.*;
import com.dropbox.sign.auth.*;
import com.dropbox.sign.model.*;

import java.io.File;
import java.util.List;

public class Example {
    public static void main(String[] args) {
        var apiClient = Configuration.getDefaultApiClient()
            .setApiKey("YOUR_API_KEY");

        var api = new SignatureRequestApi(apiClient);

        var signer1 = new SubSignatureRequestSigner()
            .emailAddress("jack@example.com")
            .name("Jack")
            .order(0);

        var signer2 = new SubSignatureRequestSigner()
            .emailAddress("jack2@example.com")
            .name("Jack 2")
            .order(1);

        var data = new SignatureRequestSendRequest()
            .title("NDA with Acme Co.")
            .subject("The NDA we talked about")
            .message("Please sign this NDA and then we can discuss more")
            .signers(List.of(signer1, signer2))
            .addFilesItem(new File("path_to/myfile.pdf"))
            .testMode(true);

        try {
            SignatureRequestGetResponse result = api.signatureRequestSend(data);
        } catch (ApiException e) {
            System.err.println("Exception when calling Dropbox Sign API");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Reason: " + e.getResponseBody());
            System.err.println("Response headers: " + e.getResponseHeaders());
            e.printStackTrace();
        }
    }
}

Create Embedded Signature Request

Legacy SDK - Create Embedded Signature RequestNew SDK - Create Embedded Signature Request

Copy

Copied

SignatureRequest request = new SignatureRequest();
request.setTitle("NDA with Acme Co.");
request.setSubject("The NDA we talked about");
request.setMessage("Please sign this NDA and then we can discuss more.");
request.addSigner("jack@example.com", "Jack");
request.addSigner("jill@example.com", "Jill");
request.addCC("lawyer@dropboxsign.com");
request.addCC("lawyer@example.com");
request.addFile(new File("nda.pdf"));
request.addFile(new File("AppendixA.pdf"));
request.setTestMode(true);

String clientId = "b6b8e7deaf8f0b95c029dca049356d4a2cf9710a";
EmbeddedRequest embedReq = new EmbeddedRequest(clientId, request);

HelloSignClient client = new HelloSignClient("API Key");
SignatureRequest newRequest = (SignatureRequest) client.createEmbeddedRequest(embedReq);

Copy

Copied

import com.dropbox.sign.ApiException;
import com.dropbox.sign.Configuration;
import com.dropbox.sign.api.*;
import com.dropbox.sign.auth.*;
import com.dropbox.sign.model.*;

import java.io.File;
import java.util.List;

public class Example {
    public static void main(String[] args) {
        var apiClient = Configuration.getDefaultApiClient()
            .setApiKey("YOUR_API_KEY");

        var api = new SignatureRequestApi(apiClient);

        var f1 = new File("./contracts/NDA/your-company-NDA.pdf");
        var f2 = new File("./contracts/NDA/Contract2.pdf");

        var signer1 = new SubSignatureRequestSigner()
            .emailAddress("jack@example.com")
            .name("Jack");

        var data = new SignatureRequestCreateEmbeddedRequest()
            .clientId("e56f0a209a842cb59f5563adafa95434")
            .title("NDA with Acme Co.")
            .subject("The NDA we talked about")
            .signers(List.of(signer1))
            .files(List.of(f1, f2))
            .testMode(true);

        try {
            SignatureRequestGetResponse result = api.signatureRequestCreateEmbedded(data);
            System.out.println(result.getSignatureRequest().getSignatures());
        } catch (ApiException e) {
            System.err.println("Exception when calling Dropbox Sign API");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Reason: " + e.getResponseBody());
            System.err.println("Response headers: " + e.getResponseHeaders());
            e.printStackTrace();
        }
    }
}

Send Non-embedded signature request with Template

Legacy SDK - Send Non-embedded SR with TemplateNew SDK - Send Non-embedded SR with Template

Copy

Copied

TemplateSignatureRequest request = new TemplateSignatureRequest();
request.setTemplateId("c26b8a16784a872da37ea946b9ddec7c1e11dff6");
request.setSubject("Purchase Order");
request.setMessage("Glad we could come to an agreement.");
request.setSigner("Client", "george@example.com", "George");
request.setCC("Accounting", "accounting@dropboxsign.com");
request.setCustomFieldValue("Cost", "$20,000");
request.setTestMode(true);

HelloSignClient client = new HelloSignClient("API_KEY");
SignatureRequest newRequest = client.sendTemplateSignatureRequest(request);

Copy

Copied

import com.dropbox.sign.ApiException;
import com.dropbox.sign.Configuration;
import com.dropbox.sign.api.*;
import com.dropbox.sign.auth.*;
import com.dropbox.sign.model.*;

import java.util.List;

public class Example {
    public static void main(String[] args) {
        var apiClient = Configuration.getDefaultApiClient()
            .setApiKey("YOUR_API_KEY");

        var api = new SignatureRequestApi(apiClient);

        var signer1 = new SubSignatureRequestTemplateSigner()
            .role("Client")
            .emailAddress("hellosign@dropboxsign.com")
            .name("George");

        var cc1 = new SubCC()
            .role("Accounting")
            .emailAddress("accouting@emaple.com");

        var customField1 = new SubCustomField()
            .name("Cost")
            .value("$20,000")
            .editor("Client")
            .required(true);

        var signingOptions = new SubSigningOptions()
            .draw(true)
            .type(true)
            .upload(true)
            .phone(false)
            .defaultType(SubSigningOptions.DefaultTypeEnum.DRAW);

        var data = new SignatureRequestSendWithTemplateRequest()
            .templateIds(List.of("b7fee29dd746ebab9d8cdfcb7cdbdd0c5a2bc67a"))
            .subject("Purchase Order")
            .message("Glad we could come to an agreement.")
            .signers(List.of(signer1))
            .ccs(List.of(cc1))
            .customFields(List.of(customField1))
            .signingOptions(signingOptions)
            .testMode(true);

        try {
            SignatureRequestGetResponse result = api.signatureRequestSendWithTemplate(data);
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Reason: " + e.getResponseBody());
            System.err.println("Response headers: " + e.getResponseHeaders());
            e.printStackTrace();
        }
    }
}

Download Files

Legacy SDK - Download FilesNew SDK - Download Files

Copy

Copied

HelloSignClient client = new HelloSignClient("API_KEY");
String signatureRequestId = "2f9781e1a8e2045224d808c153c2e1d3df6f8f2f";
File zippedFiles = client.getFiles(signatureRequestId, SignatureRequest.SIGREQ_FORMAT_ZIP);

Copy

Copied

import com.dropbox.sign.ApiException;
import com.dropbox.sign.Configuration;
import com.dropbox.sign.api.*;
import com.dropbox.sign.auth.*;

import java.io.File;

public class Example {
    public static void main(String[] args) {
        var apiClient = Configuration.getDefaultApiClient()
            .setApiKey("YOUR_API_KEY");

        var api = new SignatureRequestApi(apiClient);

        var signatureRequestId = "699d7b39ec464999aec3e0ce64a2aea5f64ba8a0";

        try {
            File result = api.signatureRequestFiles(signatureRequestId, "zip");
            result.renameTo(new File("files.zip"));
        } catch (ApiException e) {
            System.err.println("Exception");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Reason: " + e.getResponseBody());
            System.err.println("Response headers: " + e.getResponseHeaders());
            e.printStackTrace();
        }
    }
}

Get Signature Request

Legacy SDK - Get Signature RequestNew SDK - Get Signature Request

Copy

Copied

HelloSignClient client = new HelloSignClient("API_KEY");
String signatureRequestId = "fa5c8a0b0f492d768749333ad6fcc214c111e967";
SignatureRequest request = client.getSignatureRequest(signatureRequestId);

Copy

Copied

import com.dropbox.sign.ApiException;
import com.dropbox.sign.Configuration;
import com.dropbox.sign.api.*;
import com.dropbox.sign.auth.*;

import java.io.File;

public class Example {
    public static void main(String[] args) {
        var apiClient = Configuration.getDefaultApiClient()
            .setApiKey("YOUR_API_KEY");

        var api = new SignatureRequestApi(apiClient);

        var signatureRequestId = "fa5c8a0b0f492d768749333ad6fcc214c111e967";

        try {
            var result = api.signatureRequestGet(signatureRequestId);
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Reason: " + e.getResponseBody());
            System.err.println("Response headers: " + e.getResponseHeaders());
            e.printStackTrace();
        }
    }
}

List Signature Request

Legacy SDK - List Signature RequestNew SDK - List Signature Request

Copy

Copied

HelloSignClient client = new HelloSignClient("API_KEY");
SignatureRequestList list = client.getSignatureRequests(1);

Copy

Copied

import com.dropbox.sign.ApiException;
import com.dropbox.sign.Configuration;
import com.dropbox.sign.api.*;
import com.dropbox.sign.auth.*;
import com.dropbox.sign.model.*;

public class Example {
    public static void main(String[] args) {
        var apiClient = Configuration.getDefaultApiClient()
            .setApiKey("YOUR_API_KEY");

        var api = new SignatureRequestApi(apiClient);

        var accountId = "accountId OR email_address";

        try {
            SignatureRequestListResponse result = api.signatureRequestList(accountId, 1, 20, null);
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Reason: " + e.getResponseBody());
            System.err.println("Response headers: " + e.getResponseHeaders());
            e.printStackTrace();
        }
    }
}

Create Embedded Unclaimed Draft

Legacy SDK - Create Embedded Unclaimed DraftNew SDK - Create Embedded Unclaimed Draft

Copy

Copied

SignatureRequest sigReq = new SignatureRequest();
sigReq.setTestMode(true);
sigReq.addFile(new File("NDA.pdf"));

UnclaimedDraft draft = new UnclaimedDraft(sigReq, UnclaimedDraftType.request_signature);
draft.setIsForEmbeddedSigning(false);
draft.setRequesterEmail("jack@dropboxsign.com");

String clientId = "ca1209bc08912a8a881234def21352ab";
EmbeddedRequest embedReq = new EmbeddedRequest(clientId, draft);

HelloSignClient client = new HelloSignClient("API_KEY");
UnclaimedDraft responseDraft = (UnclaimedDraft) client.createEmbeddedRequest(embedReq);

Copy

Copied

import com.dropbox.sign.ApiException;
import com.dropbox.sign.Configuration;
import com.dropbox.sign.api.*;
import com.dropbox.sign.auth.*;
import com.dropbox.sign.model.*;

import java.util.List;

public class Example {
    public static void main(String[] args) {
        var apiClient = Configuration.getDefaultApiClient()
            .setApiKey("YOUR_API_KEY");

        var api = new UnclaimedDraftApi(apiClient);

        var data = new UnclaimedDraftCreateEmbeddedRequest()
            .clientId("ec64a202072370a737edf4a0eb7f4437")
            .fileUrls(List.of("https://app.hellosign.com/docs/example_signature_request.pdf"))
            .requesterEmailAddress("jack@dropboxsign.com")
            .testMode(true);

        try {
            UnclaimedDraftCreateResponse result = api.unclaimedDraftCreateEmbedded(data);
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception when calling Dropbox Sign API");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Reason: " + e.getResponseBody());
            System.err.println("Response headers: " + e.getResponseHeaders());
            e.printStackTrace();
        }
    }
}

Create Embedded Template - With Merge Fields

Legacy SDK - Create Embedded TemplateNew SDK - Create Embedded Template

Copy

Copied

TemplateDraft draft = new TemplateDraft();
draft.setTestMode(true);
draft.setTitle("NDA Template");
draft.addSignerRole("Client");
draft.addCCRole("Lawyer");
draft.addFile(getTestFile("nda.pdf"));

EmbeddedRequest eReq = new EmbeddedRequest(clientId, draft);
HelloSignClient client = new HelloSignClient("API_KEY");
TemplateDraft t = client.createEmbeddedTemplateDraft(eReq);

Copy

Copied

import com.dropbox.sign.ApiException;
import com.dropbox.sign.Configuration;
import com.dropbox.sign.api.*;
import com.dropbox.sign.auth.*;
import com.dropbox.sign.model.*;

import java.io.File;
import java.util.List;

public class Example {
    public static void main(String[] args) {
        var apiClient = Configuration.getDefaultApiClient()
            .setApiKey("YOUR_API_KEY");

        var api = new TemplateApi(apiClient);

        var role1 = new SubTemplateRole()
            .name("Client")
            .order(0);

        var role2 = new SubTemplateRole()
            .name("Witness")
            .order(1);

        var mergeField1 = new SubMergeField()
            .name("Full Name")
            .type(SubMergeField.TypeEnum.TEXT);

        var mergeField2 = new SubMergeField()
            .name("Is Registered?")
            .type(SubMergeField.TypeEnum.CHECKBOX);

        var fieldOptions = new SubFieldOptions()
            .dateFormat(SubFieldOptions.DateFormatEnum.DDMMYYYY);

        var data = new TemplateCreateEmbeddedDraftRequest()
            .clientId("e56f0a209a842cb59f5563adafa95434")
            .title("Test Template")
            .addFilesItem(new File("./contracts/NDA/Contract2.pdf.pdf"))
            .subject("Please sign this document")
            .message("For your approval")
            .signerRoles(List.of(role1, role2))
            .mergeFields(List.of(mergeField1, mergeField2))
            .fieldOptions(fieldOptions)
            .testMode(true);

        try {
            TemplateCreateEmbeddedDraftResponse result = api.templateCreateEmbeddedDraft(data);
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Reason: " + e.getResponseBody());
            System.err.println("Response headers: " + e.getResponseHeaders());
            e.printStackTrace();
        }
    }
}

Create API APP

Legacy SDK - Create API AppNew SDK - Create API App

Copy

Copied

ApiApp app = new ApiApp();

WhiteLabelingOptions wl= new WhiteLabelingOptions();
wl.setPrimaryButtonHoverColor("#4B1414");
wl.setHeaderBackgroundColor("#171616");

app.setWhiteLabelingOptions(wl);
app.setDomain("www.example.com");
app.setName("Test API App");
app.getClientId();

client.createApiApp(app);

Copy

Copied

import com.dropbox.sign.ApiException;
import com.dropbox.sign.Configuration;
import com.dropbox.sign.api.*;
import com.dropbox.sign.auth.*;
import com.dropbox.sign.model.*;

import java.util.List;

public class Example {
    public static void main(String[] args) {
        var apiClient = Configuration.getDefaultApiClient()
            .setApiKey("YOUR_API_KEY");

        var api = new ApiAppApi(apiClient);

        var wl = new SubWhiteLabelingOptions()
            .primaryButtonTextColor("171616")
            .headerBackgroundColor("4B1414")
            .legalVersion(SubWhiteLabelingOptions.LegalVersionEnum.TERMS2);

        var data = new ApiAppCreateRequest ()
            .name("My Test App")
            .domains(List.of("example.com"))
            .callbackUrl("https://callbackurl.com")
            .whiteLabelingOptions(wl);

        try {
            ApiAppGetResponse result = api.apiAppCreate(data);
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Reason: " + e.getResponseBody());
            System.err.println("Response headers: " + e.getResponseHeaders());
            e.printStackTrace();
        }
    }
}

Supporting Legacy SDKs

Following the official release of the new SDK version, we'll be preparing to deprecate all legacy versions of the Java SDK for one year after launch. That means, once fully launched, we'll only support critical vulnerabilities and bug fixes for legacy SDK versions 5.2.3 for 12 months. After that, legacy versions are considered officially deprecated and are no longer supported. You can find more information in our SDK Versioning Policy.

We encourage you to start migrating (or planning to migrate) to the new SDK as soon as possible. Please don't hesitate to reach out if you have questions or need assistance.

Feedback and Assistance

We know that dealing with "breaking" changes is inconvenient for those of you currently using the legacy SDK, but believe the new SDK offers a better experience while providing access to more features. If you need help or get stuck, please reach out to API support: Submit a Ticket

We warmly welcome your feedback, feature requests, and bug reports in our OpenAPI repo. All of the engineering work on the Java SDK happens in the Java folder of the repo.

Java Migration Guide

Migrating the Java SDK from hellosign-java-sdk to dropbox-sign

Architecture and Tooling

SDK Resources

Core Concepts and Patterns

Installation

Importing the SDK

Authentication

Endpoints Grouped into Classes

Using Models to Pass Parameters

Path and Query Parameters

Error Handling and Warnings

Error Handling

Warnings

Instantiating Objects From Data

Note

Event Callback Helper

Differences from Legacy SDK

Form Fields per Document

Instantiating the Correct Field Class

"role" Value in signers Object

"role" Value in ccs Property

"name" Value in custom_fields Property

template_id to template_ids

file to files

file_url to file_urls

Interacting with Files

Uploading Files

Using the set File method

Downloading Files

Endpoint mapping

Send Non-Embedded Signature Request

Create Embedded Signature Request

Send Non-embedded signature request with Template

Download Files

Get Signature Request

List Signature Request

Create Embedded Unclaimed Draft

Create Embedded Template - With Merge Fields

Create API APP

Supporting Legacy SDKs

Feedback and Assistance

Migrating the Java SDK from `hellosign-java-sdk` to `dropbox-sign`

"role" Value in `signers` Object

"role" Value in `ccs` Property

"name" Value in `custom_fields` Property

`template_id` to `template_ids`

`file` to `files`

`file_url` to `file_urls`