# Java

> Use this guide to migrate to the new Dropbox Sign Java SDK, which is powered by our OpenAPI specification. Contains concepts and examples to help you migrate successfully.

# Java Migration Guide

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

<SdkIntro sdkLanguage="Java" sdkRepoUrl="https://search.maven.org/artifact/com.dropbox.sign/dropbox-sign" />

## Architecture and Tooling

<SdkUsage sdkLanguage="Java" sdkRepoUrl="https://search.maven.org/artifact/com.dropbox.sign/dropbox-sign" sdkPackageManager="maven" sdkName="dropbox-sign" referenceLink="https://github.com/hellosign/dropbox-sign-java/blob/main/README.md#getting-started" examplesLink="https://github.com/hellosign/dropbox-sign-java/tree/main/examples" />

## 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](https://mvnrepository.com/) or [Gradle](https://gradle.org/).

<CodeBlocks>
  ```xml Using Maven (v2 with jakarta)
  <dependency>
    <groupId>com.dropbox.sign</groupId>
    <artifactId>dropbox-sign</artifactId>
    <version>2.x.x-</version>
  </dependency>
  ```

  ```groovy Using Gradle (v2 with jakarta)
  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"
  }
  ```

  ```xml Using Maven (v1 with javax)
  <dependency>
    <groupId>com.dropbox.sign</groupId>
    <artifactId>dropbox-sign</artifactId>
    <version>1.x.x-</version>
  </dependency>
  ```

  ```groovy Using Gradle (v1 with javax)
  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"
  }
  ```
</CodeBlocks>

<HR />

### Importing the SDK

<CodeBlocks>
  ```java Legacy SDK - Namespaces
  import com.hellosign.sdk;
  ```

  ```java New SDK - Namespaces
  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.*;
  ```
</CodeBlocks>

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                    |

<HR />

### Authentication

This section covers how to authenticate and configure your API Key or [OAuth token](/docs/guides/o-auth/overview) 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.

<CodeBlocks>
  ```java Legacy SDK- Client API Key
  HelloSignClient client = new HelloSignClient(apiKey);
  ```

  ```java New SDK - Client API Key
  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");
      }
  }
  ```

  ```java Legacy SDK - Client Access Token
  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();

  ```

  ```java New SDK - Client Access Token
  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");
      }
  }
  ```
</CodeBlocks>

<HR />

### Endpoints Grouped into Classes

The new SDK divides endpoints across unique Classes:

| Class Name and Reference                                                                                    | API Reference                                              |
| ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| [AccountApi](https://github.com/hellosign/dropbox-sign-java/blob/main/docs/AccountApi.md)                   | [/account/\* Endpoints](/api/account)                      |
| [ApiAppApi](https://github.com/hellosign/dropbox-sign-java/blob/main/docs/ApiAppApi.md)                     | [/api\_app/\* Endpoints](/api/api-app)                     |
| [BulkSendJobApi](https://github.com/hellosign/dropbox-sign-java/blob/main/docs/BulkSendJobApi.md)           | [/bulk\_send\_job/\* Endpoints](/api/bulk-send-job)        |
| [EmbeddedApi](https://github.com/hellosign/dropbox-sign-java/blob/main/docs/EmbeddedApi.md)                 | [/embedded/\* Endpoints](/api/embedded)                    |
| [OAuthApi](https://github.com/hellosign/dropbox-sign-java/blob/main/docs/OAuthApi.md)                       | [/oauth/\* Endpoints](/docs/guides/o-auth/overview)        |
| [ReportApi](https://github.com/hellosign/dropbox-sign-java/blob/main/docs/ReportApi.md)                     | [/report/\* Endpoints](/api/report)                        |
| [SignatureRequestApi](https://github.com/hellosign/dropbox-sign-java/blob/main/docs/SignatureRequestApi.md) | [/signature\_request/\* Endpoints](/api/signature-request) |
| [TeamApi](https://github.com/hellosign/dropbox-sign-java/blob/main/docs/TeamApi.md)                         | [/team/\* Endpoints](/api/team)                            |
| [TemplateApi](https://github.com/hellosign/dropbox-sign-java/blob/main/docs/TemplateApi.md)                 | [/template/\* Endpoints](/api/template)                    |
| [UnclaimedDraftApi](https://github.com/hellosign/dropbox-sign-java/blob/main/docs/UnclaimedDraftApi.md)     | [/unclaimed\_draft/\* Endpoints](/api/unclaimed-draft)     |

<HR />

### Using Models to Pass Parameters

[Models](https://github.com/hellosign/dropbox-sign-java/blob/main/README.md#documentation-for-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**

```java
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();
        }
    }
}
```

<HR />

### 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**

```java
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**

```java
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();
        }
    }
}
```

<HR />

### 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](https://github.com/hellosign/dropbox-sign-java/blob/main/src/main/java/com/dropbox/sign/ApiException.java) with its `getErrorResponse()` method returning an instance of [com.dropbox.sign.model.ErrorResponse](https://github.com/hellosign/dropbox-sign-java/blob/main/src/main/java/com/dropbox/sign/model/ErrorResponse.java) class and should be handled using Try/Catch blocks.

<CodeBlocks>
  ```java New SDK - Error Handling
  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();
          }
      }
  }
  ```
</CodeBlocks>

#### Warnings

Warnings are a list of [com.dropbox.sign.model.WarningResponse](https://github.com/hellosign/dropbox-sign-java/blob/main/src/main/java/com/dropbox/sign/model/WarningResponse.java).

**New SDK - Warnings**

```java
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();
        }
    }
}
```

<HR />

### 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

<CodeBlocks>
  ```java New SDK - Using setter methods
  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);
  ```

  ```java New SDK - Using init() Static Method
  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);
      }})
  );
  ```
</CodeBlocks>

<Info title="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`).
</Info>

<HR />

### Event Callback Helper

A callback helper class is included in the [New SDK repo](https://github.com/hellosign/dropbox-sign-java/blob/main/src/main/java/com/dropbox/sign/EventCallbackHelper.java) to assist in verifying callbacks. The helper simplifies:

1. Checking event authenticity with built in event hash check
2. Displaying event types (account callback vs. app callback)
3. 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**

```bash
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**

```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
    }
  }
}
```

**How to use the EventCallbackHelper**

```java
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!
        }
    }
}
```

<HR />

## 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](/docs/sd-ks/open-api/form-fields-per-document).

<CodeBlocks>
  ```java Legacy SDK - Form Fields Per Document
  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);
  ```

  ```java New SDK - Form Fields per Document
  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();
          }
      }
  }
  ```
</CodeBlocks>

#### 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](https://github.com/hellosign/dropbox-sign-java/blob/main/src/main/java/com/dropbox/sign/model/SubFormFieldsPerDocumentCheckbox.java)           |
| checkbox-merge | [SubFormFieldsPerDocumentCheckboxMerge](https://github.com/hellosign/dropbox-sign-java/blob/main/src/main/java/com/dropbox/sign/model/SubFormFieldsPerDocumentCheckboxMerge.java) |
| date\_signed   | [SubFormFieldsPerDocumentDateSigned](https://github.com/hellosign/dropbox-sign-java/blob/main/src/main/java/com/dropbox/sign/model/SubFormFieldsPerDocumentDateSigned.java)       |
| dropdown       | [SubFormFieldsPerDocumentDropdown](https://github.com/hellosign/dropbox-sign-java/blob/main/src/main/java/com/dropbox/sign/model/SubFormFieldsPerDocumentDropdown.java)           |
| hyperlink      | [SubFormFieldsPerDocumentHyperlink](https://github.com/hellosign/dropbox-sign-java/blob/main/src/main/java/com/dropbox/sign/model/SubFormFieldsPerDocumentHyperlink.java)         |
| initials       | [SubFormFieldsPerDocumentInitials](https://github.com/hellosign/dropbox-sign-java/blob/main/src/main/java/com/dropbox/sign/model/SubFormFieldsPerDocumentInitials.java)           |
| radio          | [SubFormFieldsPerDocumentRadio](https://github.com/hellosign/dropbox-sign-java/blob/main/src/main/java/com/dropbox/sign/model/SubFormFieldsPerDocumentRadio.java)                 |
| signature      | [SubFormFieldsPerDocumentSignature](https://github.com/hellosign/dropbox-sign-java/blob/main/src/main/java/com/dropbox/sign/model/SubFormFieldsPerDocumentSignature.java)         |
| text           | [SubFormFieldsPerDocumentText](https://github.com/hellosign/dropbox-sign-java/blob/main/src/main/java/com/dropbox/sign/model/SubFormFieldsPerDocumentText.java)                   |
| text-merge     | [SubFormFieldsPerDocumentTextMerge](https://github.com/hellosign/dropbox-sign-java/blob/main/src/main/java/com/dropbox/sign/model/SubFormFieldsPerDocumentTextMerge.java)         |

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

```java
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**

```java
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**

```java
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:**

<CodeBlocks>
  ```java Signature
  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);
  }});
  ```

  ```java Initials
  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);
  }});
  ```

  ```java Date Signed
  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);
  }});
  ```

  ```java Text
  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);
  }});
  ```

  ```java Text Merge
  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);
  }});
  ```

  ```java Checkbox
  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);
  }});
  ```

  ```java Checkbox Merge
  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);
  }});
  ```

  ```java Dropdown
  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");
  }});
  ```

  ```java Hyperlink
  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");
  }});
  ```

  ```java Radio
  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");
  }});
  ```
</CodeBlocks>

<HR />

### "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](/api/signature-request/send-with-template) endpoint the `signers` property could be represented as:

<CodeBlocks>
  ```json Legacy SDK - signers with Roles
  {
    "signers": {
      "Client": {
        "name": "George",
        "email_address": "george@example.com"
      },
      "Manager": {
        "name": "Bob",
        "email_address": "bob@example.com"
      }
    }
  }
  ```

  ```json New SDK - signers with Roles
  {
    "signers": [
      {
        "role": "Client",
        "name": "George",
        "email_address": "george@example.com"
      },
      {
        "role": "Manager",
        "name": "Bob",
        "email_address": "bob@example.com"
      }
    ]
  }
  ```
</CodeBlocks>

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

<CodeBlocks>
  ```java New SDK - signers with Roles Example #1
  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();
          }
      }
  }
  ```

  ```java New SDK - signers with Roles Example #2
  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();
          }
      }
  }
  ```
</CodeBlocks>

<HR />

### "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](/api/signature-request/send-with-template) endpoint the `ccs` property could be represented as:

<CodeBlocks>
  ```json Legacy SDK - ccs
  {
    "ccs": {
      "Client": "george@example.com",
      "Manager": "bob@example.com"
    }
  }
  ```

  ```json New SDK - ccs
  {
    "ccs": [
      {
        "role": "Client",
        "email_address": "george@example.com"
      },
      {
        "role": "Manager",
        "email_address": "bob@example.com"
      }
    ]
  }
  ```
</CodeBlocks>

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

<CodeBlocks>
  ```java New SDK - ccs Example #1
  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();
          }
      }
  }
  ```

  ```java New SDK - ccs Example #2
  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();
          }
      }
  }
  ```
</CodeBlocks>

<HR />

### "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](/api/signature-request/send-with-template) endpoint the `custom_fields` property could be represented as:

<CodeBlocks>
  ```json Legacy SDK - custom_fields
  {
    "custom_fields": {
      "company": {
        "value": "ABC Corp",
        "required": true
      }
    }
  }
  ```

  ```json New SDK - custom_fields
  {
    "custom_fields": [
      {
        "name": "company",
        "value": "ABC Corp",
        "required": true
      }
    ]
  }
  ```
</CodeBlocks>

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

<CodeBlocks>
  ```java New SDK - custom_fields Example #1
  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();
          }
      }
  }
  ```

  ```java New SDK - custom_fields Example #2
  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();
          }
      }
  }
  ```
</CodeBlocks>

<HR />

### `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:<br /><br /><pre><code>template\_id : "1234567890"</code></pre> | Template ID is passed as an array of strings (`template_ids`): <br /><br /><pre><code>template\_ids:\["1234567890"]</code></pre> |

<HR />

### `file` to `files`

The `file` parameter has been renamed to `files`. Usage remains the same.

Use `.files([...])`;

<HR />

### `file_url` to `file_urls`

The `file_url` parameter has been renamed to `file_urls`. Usage remains the same.

Use `.fileUrls([...])`;

<HR />

### 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](/docs/sd-ks/open-api/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

<CodeBlocks>
  ```java Legacy SDK - Adding Files
  //Using the Document Class
  Document doc1 = new Document();
  doc1.setFile(new File("/NDA.pdf"));
  ```

  ```java New SDK - addFilesItem method
  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"))
  ```

  ```java New SDK - files method
  // 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));
  ```
</CodeBlocks>

<CodeBlocks>
  ```java New SDK - setFiles method
  // 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));
  ```
</CodeBlocks>

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

<Warning title="Using the set File method" icon="fa-light fa-circle-exclamation">
  Because the `setFile` method return type is `void`, this method must be chained together with the Object, as shown on the example above.
</Warning>

<HR />

#### 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](https://github.com/hellosign/dropbox-sign-java/blob/main/docs/SignatureRequestApi.md#signatureRequestFiles)           | [Download template files as .pdf/zip](https://github.com/hellosign/dropbox-sign-java/blob/main/docs/TemplateApi.md#templateFiles)                                                                                                                    |
| [Download files as file\_url](https://github.com/hellosign/dropbox-sign-java/blob/main/docs/SignatureRequestApi.md#signatureRequestFilesAsFileUrl) | \[Download template files as file\_url] ([https://github.com/hellosign/dropbox-sign-java/blob/main/docs/TemplateApi.md#templateFilesAsFileUrl](https://github.com/hellosign/dropbox-sign-java/blob/main/docs/TemplateApi.md#templateFilesAsFileUrl)) |
| [Download files as data\_url](https://github.com/hellosign/dropbox-sign-java/blob/main/docs/SignatureRequestApi.md#signatureRequestFilesAsDataUri) | \[Download template files as data\_url] ([https://github.com/hellosign/dropbox-sign-java/blob/main/docs/TemplateApi.md#templateFilesAsDataUri](https://github.com/hellosign/dropbox-sign-java/blob/main/docs/TemplateApi.md#templateFilesAsDataUri)) |

<CodeBlocks>
  ```java New SDK - Download Files
  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();
          }
      }
  }
  ```

  ```java New SDK - Download as Data Uri
  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();
          }
      }
  }
  ```

  ```java New SDK - File File Url
  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();
          }
      }
  }
  ```
</CodeBlocks>

**Downloading Templates**

<CodeBlocks>
  ```java New SDK - Download Template Files
  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();
          }
      }
  }
  ```

  ```java New SDK - Template File as Data Uri
  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();
          }
      }
  }
  ```

  ```java New SDK - Template File as File Url
  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();
          }
      }
  }
  ```
</CodeBlocks>

<HR />

## 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](https://faq.hellosign.com/hc/en-us/requests/new) if you think we're missing an important example.

* [Send Non-Embedded Signature Request](#send-non-embedded-signature-request)
* [Create Embedded Signature Request](#create-embedded-signature-request)
* [Send Non-Embedded Signature Request with Template](#send-non-embedded-signature-request-with-template)
* [Download Files](#download-files)
* [Get Signature Request](#get-signature-request)
* [List Signature Request](#list-signature-request)
* [Create Embedded Unclaimed Draft](#create-embedded-unclaimed-draft)
* [Create Embedded Template- with Merge Fields](#create-embedded-template---with-merge-fields)
* [Create API App - with WhiteLabelingOptions](#create-api-app)

### Send Non-Embedded Signature Request

<CodeBlocks>
  ```java Legacy SDK - Non-Embedded Signature
  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());
  ```

  ```java New SDK - Non-Embedded Signature
  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();
          }
      }
  }
  ```
</CodeBlocks>

<HR />

### Create Embedded Signature Request

<CodeBlocks>
  ```java Legacy SDK - Create Embedded Signature Request
  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);
  ```

  ```java New SDK - Create Embedded Signature Request
  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();
          }
      }
  }
  ```
</CodeBlocks>

<HR />

### Send Non-embedded signature request with Template

<CodeBlocks>
  ```java Legacy SDK - Send Non-embedded SR with Template
  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);
  ```

  ```java New SDK - Send Non-embedded SR with Template
  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();
          }
      }
  }
  ```
</CodeBlocks>

<HR />

### Download Files

<CodeBlocks>
  ```java Legacy SDK - Download Files
  HelloSignClient client = new HelloSignClient("API_KEY");
  String signatureRequestId = "2f9781e1a8e2045224d808c153c2e1d3df6f8f2f";
  File zippedFiles = client.getFiles(signatureRequestId, SignatureRequest.SIGREQ_FORMAT_ZIP);
  ```

  ```java New SDK - Download Files
  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();
          }
      }
  }
  ```
</CodeBlocks>

<HR />

### Get Signature Request

<CodeBlocks>
  ```java Legacy SDK - Get Signature Request
  HelloSignClient client = new HelloSignClient("API_KEY");
  String signatureRequestId = "fa5c8a0b0f492d768749333ad6fcc214c111e967";
  SignatureRequest request = client.getSignatureRequest(signatureRequestId);
  ```

  ```java New SDK - Get Signature Request
  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();
          }
      }
  }
  ```
</CodeBlocks>

<HR />

### List Signature Request

<CodeBlocks>
  ```java Legacy SDK - List Signature Request
  HelloSignClient client = new HelloSignClient("API_KEY");
  SignatureRequestList list = client.getSignatureRequests(1);
  ```

  ```java New SDK - List Signature Request
  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();
          }
      }
  }
  ```
</CodeBlocks>

<HR />

### Create Embedded Unclaimed Draft

<CodeBlocks>
  ```java Legacy SDK - Create Embedded Unclaimed Draft
  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);
  ```

  ```java New SDK - Create Embedded Unclaimed Draft
  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();
          }
      }
  }
  ```
</CodeBlocks>

<HR />

### Create Embedded Template - With Merge Fields

<CodeBlocks>
  ```java Legacy SDK - Create Embedded Template
  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);
  ```

  ```java New SDK - Create Embedded Template
  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();
          }
      }
  }
  ```
</CodeBlocks>

<HR />

### Create API APP

<CodeBlocks>
  ```java Legacy SDK - Create API App
  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);
  ```

  ```java New SDK - Create API App
  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();
          }
      }
  }
  ```
</CodeBlocks>

<HR />

## Supporting Legacy SDKs

<SdkLogistics sdkLanguage="Java" sdkLegacyVersion="5.2.3" />

<HR />

## Feedback and Assistance

<SdkFeedback sdkLanguage="Java" />