DocuSign Java Client

You can sign up for a free developer sandbox.

Requirements

Java 1.6 or later.

Installation

Maven users

Add this dependency to your project's POM:

<dependency>
   <groupId>com.docusign</groupId>
   <artifactId>docusign-esign-java</artifactId>
   <version>2.2.0</version>
</dependency>

Gradle users

Add this dependency to your project's build file:

compile "com.docusign:docusign-esign-java:2.2.0"

Dependencies

This client has the following external dependencies:

• io.swagger:swagger-annotations:jar:1.5.8
• com.sun.jersey:jersey-client:jar:1.19.1
• com.sun.jersey.contribs:jersey-multipart:jar:1.19.1
• com.fasterxml.jackson.core:jackson-core:jar:2.7.0
• com.fasterxml.jackson.core:jackson-annotations:jar:2.7.0
• com.fasterxml.jackson.core:jackson-databind:jar:2.7.0
• com.fasterxml.jackson.jaxrs:jackson-jaxrs-json-provider:jar:2.7.0
• com.fasterxml.jackson.datatype:jackson-datatype-joda:jar:2.1.5
• joda-time:joda-time:jar:2.9.3
• com.brsanthu:migbase64:jar:2.2
• junit:junit:jar:4.12

Note for Android Developers

If you encounter build errors due to duplicate definitions, include the following in your build.gradle module:

android {
   packagingOptions {
      pickFirst 'META-INF/services/javax.ws.rs.ext.MessageBodyReader’
      pickFirst 'META-INF/services/javax.ws.rs.ext.MessageBodyWriter’
      pickFirst 'META-INF/services/com.sun.jersey.spi.inject.InjectableProvider’
      pickFirst 'META-INF/jersey-module-version' pickFirst 'META-INF/NOTICE’
      pickFirst 'META-INF/LICENSE’
      pickFirst 'META-INF/services/com.fasterxml.jackson.databind.Module’
      pickFirst 'META-INF/services/com.fasterxml.jackson.core.ObjectCodec’
      pickFirst 'META-INF/services/com.fasterxml.jackson.core.JsonFactory’
   }
}

Package Managers

This client is available through the following Java package managers:

• Nexus Repository Manager (oss.sonatype.org). You can search for com.docusign or docusign-esign-java. The current version is 2.2.0.
• JFrog Bintray (bintray.com). You can search for com.docusign or docusign-esign-java. The current version is 2.2.0.

Others

Or you can manually download and add the following JARs to your project:

• The docusign-esign-java-2.2.0 JAR.
• The Dependency JARs in /lib folder.

Usage

To send a signature request from a Template using 3-legged OAuth:

import com.docusign.esign.api.*;
import com.docusign.esign.client.*;
import com.docusign.esign.model.*;
import com.docusign.esign.client.auth.OAuth.AccessTokenListener;

import org.apache.oltu.oauth2.common.token.BasicOAuthToken;
import java.awt.Desktop;

public class DocuSignExample {
  public static void main(String[] args) {
    String RedirectURI = "[REDIRECT_URI]";
    String ClientSecret = "[CLIENT_SECRET]";
    String integratorKey = "[INTEGRATOR_KEY]";
    String BaseUrl = "https://demo.docusign.net/restapi";
    String OAuthBaseUrl = "https://account-d.docusign.com";
    
    ApiClient apiClient = new ApiClient(OAuthBaseUrl, "docusignAccessCode", IntegratorKey, ClientSecret);
    apiClient.setBasePath(BaseUrl);
    // make sure to pass the redirect uri
    apiClient.configureAuthorizationFlow(IntegratorKey, ClientSecret, RedirectURI);
    Configuration.setDefaultApiClient(apiClient);
    try
    {
      // get DocuSign OAuth authorization url
      String oauthLoginUrl = apiClient.getAuthorizationUri();
      // open DocuSign OAuth login in the browser
      System.out.println(oauthLoginUrl);
      Desktop.getDesktop().browse(URI.create(oauthLoginUrl));
      // IMPORTANT: after the login, DocuSign will send back a fresh
      // authorization code as a query param of the redirect URI.
      // You should set up a route that handles the redirect call to get
      // that code and pass it to token endpoint as shown in the next
      // lines:
      String code = "<once_you_get_the_oauth_code_put_it_here>";
      // assign it to the token endpoint
      apiClient.getTokenEndPoint().setCode(code);
      // optionally register to get notified when a new token arrives
      apiClient.registerAccessTokenListener(new AccessTokenListener() {
        @Override
        public void notify(BasicOAuthToken token) {
          System.out.println("Got a fresh token: " + token.getAccessToken());
        }
      });
      // ask to exchange the auth code with an access code
      apiClient.updateAccessToken();
    
      /////////////////////////////////////////////////////////////////////////////////////////////////////////
      // STEP 1: AUTHENTICATE TO RETRIEVE ACCOUNTID & BASEURL         
      /////////////////////////////////////////////////////////////////////////////////////////////////////////

      AuthenticationApi authApi = new AuthenticationApi(apiClient);
      LoginInformation loginInfo = authApi.login();
      
      // parse first account ID (user might belong to multiple accounts) and baseUrl
      String accountId = loginInfo.getLoginAccounts().get(0).getAccountId(); 
      String baseUrl = loginInfo.getLoginAccounts().get(0).getBaseUrl();
      String[] accountDomain = baseUrl.split("/v2");
      
      // below code required for production, no effect in demo (same domain) 
      apiClient.setBasePath(accountDomain[0]);
      Configuration.setDefaultApiClient(apiClient);
      
      /////////////////////////////////////////////////////////////////////////////////////////////////////////
      // *** STEP 2: CREATE ENVELOPE FROM TEMPLATE       
      /////////////////////////////////////////////////////////////////////////////////////////////////////////
      
      // create a new envelope to manage the signature request
      EnvelopeDefinition envDef = new EnvelopeDefinition();
      envDef.setEmailSubject("DocuSign Java SDK - Sample Signature Request");
      
      // assign template information including ID and role(s)
      envDef.setTemplateId("[TEMPLATE_ID]");
      
      // create a template role with a valid templateId and roleName and assign signer info
      TemplateRole tRole = new TemplateRole();
      tRole.setRoleName("[ROLE_NAME]");
      tRole.setName("[SIGNER_NAME]");
      tRole.setEmail("[SIGNER_EMAIL]");
    
      // create a list of template roles and add our newly created role
      java.util.List<TemplateRole> templateRolesList = new java.util.ArrayList<TemplateRole>();
      templateRolesList.add(tRole);
    
      // assign template role(s) to the envelope 
      envDef.setTemplateRoles(templateRolesList);
      
      // send the envelope by setting |status| to "sent". To save as a draft set to "created"
      envDef.setStatus("sent");
    
      // instantiate a new EnvelopesApi object
      EnvelopesApi envelopesApi = new EnvelopesApi(apiClient);
    
      // call the createEnvelope() API
      EnvelopeSummary envelopeSummary = envelopesApi.createEnvelope(accountId, envDef);
    }
    catch (com.docusign.esign.client.ApiException ex)
    {
      System.out.println("Exception: " + ex);
    }
  }
} 

To send a signature request from a Template using username/password:

import com.docusign.esign.api.*;
import com.docusign.esign.client.*;
import com.docusign.esign.model.*;

import java.util.List;

public class DocuSignExample {
  public static void main(String[] args) {
    String username = "[EMAIL]";
    String password = "[PASSWORD]";
    String integratorKey = "[INTEGRATOR_KEY]";
    
    // initialize client for desired environment and add X-DocuSign-Authentication header
    ApiClient apiClient = new ApiClient("https://demo.docusign.net/restapi");
    
    // configure 'X-DocuSign-Authentication' authentication header
    String authHeader = "{\"Username\":\"" +  username + "\",\"Password\":\"" +  password + "\",\"IntegratorKey\":\"" +  integratorKey + "\"}";
    // If you have an OAuth access token stored in a variable named 'access_token', let's say, then instead, you can set authHeader as following (notice the extra space after 'Bearer'):
    // String authHeader = "{\"Bearer \":\"" +  access_token + "\"}";
    apiClient.addDefaultHeader("X-DocuSign-Authentication", authHeader);
    Configuration.setDefaultApiClient(apiClient);
    try
    {
      /////////////////////////////////////////////////////////////////////////////////////////////////////////
      // STEP 1: AUTHENTICATE TO RETRIEVE ACCOUNTID & BASEURL         
      /////////////////////////////////////////////////////////////////////////////////////////////////////////

      AuthenticationApi authApi = new AuthenticationApi();
      LoginInformation loginInfo = authApi.login();
      
      // parse first account ID (user might belong to multiple accounts) and baseUrl
      String accountId = loginInfo.getLoginAccounts().get(0).getAccountId(); 
      String baseUrl = loginInfo.getLoginAccounts().get(0).getBaseUrl();
      String[] accountDomain = baseUrl.split("/v2");
      
      // below code required for production, no effect in demo (same domain) 
      apiClient.setBasePath(accountDomain[0]);
      Configuration.setDefaultApiClient(apiClient);
      
      /////////////////////////////////////////////////////////////////////////////////////////////////////////
      // *** STEP 2: CREATE ENVELOPE FROM TEMPLATE       
      /////////////////////////////////////////////////////////////////////////////////////////////////////////
      
      // create a new envelope to manage the signature request
      EnvelopeDefinition envDef = new EnvelopeDefinition();
      envDef.setEmailSubject("DocuSign Java SDK - Sample Signature Request");
      
      // assign template information including ID and role(s)
      envDef.setTemplateId("[TEMPLATE_ID]");
      
      // create a template role with a valid templateId and roleName and assign signer info
      TemplateRole tRole = new TemplateRole();
      tRole.setRoleName("[ROLE_NAME]");
      tRole.setName("[SIGNER_NAME]");
      tRole.setEmail("[SIGNER_EMAIL]");
    
      // create a list of template roles and add our newly created role
      java.util.List<TemplateRole> templateRolesList = new java.util.ArrayList<TemplateRole>();
      templateRolesList.add(tRole);
    
      // assign template role(s) to the envelope 
      envDef.setTemplateRoles(templateRolesList);
      
      // send the envelope by setting |status| to "sent". To save as a draft set to "created"
      envDef.setStatus("sent");
    
      // instantiate a new EnvelopesApi object
      EnvelopesApi envelopesApi = new EnvelopesApi();
    
      // call the createEnvelope() API
      EnvelopeSummary envelopeSummary = envelopesApi.createEnvelope(accountId, envDef);
    }
    catch (com.docusign.esign.client.ApiException ex)
    {
      System.out.println("Exception: " + ex);
    }
  }
} 

See SdkUnitTests.java for more examples.

Authentication

Service Integrations that use Legacy Header Authentication

(Legacy Header Authentication uses the X-DocuSign-Authentication header.)

1. Use the Authentication: login method to retrieve the account number and the baseUrl for the account. The url for the login method is www.docusign.net for production and demo.docusign.net for the developer sandbox. The baseUrl field is part of the loginAccount object. See the docs and the loginAccount object
2. The baseUrl for the selected account, in production, will start with na1, na2, na3, eu1, or something else. Use the baseUrl that is returned to create the basePath (see the next step.) Use the basePath for all of your subsequent API calls.
3. As returned by login method, the baseUrl includes the API version and account id. Split the string to obtain the basePath, just the server name and api name. Eg, you will receive https://na1.docusign.net/restapi/v2/accounts/123123123. You want just https://na1.docusign.net/restapi
4. Instantiate the SDK using the basePath. Eg ApiClient apiClient = new ApiClient(basePath);
5. Set the authentication header as shown in the examples by using Configuration.Default.AddDefaultHeader

User Applications that use OAuth Authentication

1. After obtaining a Bearer token, call the OAuth: Userinfo method. Obtain the selected account's base_uri (server name) field. The url for the Userinfo method is account-d.docusign.com for the demo/developer environment, and account.docusign.com for the production environment.
2. Combine the base_uri with "/restapi" to create the basePath. The base_uri will start with na1, na2, na3, eu1, or something else. Use the basePath for your subsequent API calls.
3. Instantiate the SDK using the basePath. Eg ApiClient apiClient = new ApiClient(basePath);
4. Create the authentication_value by combining the token_type and access_token fields you receive from either an Authorization Code Grant or Implicit Grant OAuth flow.
5. Set the authentication header by using Configuration.Default.AddDefaultHeader('Authorization', authentication_value)

Testing

You must have Maven installed. To run the tests:

mvn test

Support

Feel free to log issues against this client through GitHub. We also have an active developer community on Stack Overflow, search the DocuSignAPI tag.

License

The DocuSign Java Client is licensed under the following License.