com.hellosign.sdk

Class HelloSignClient

java.lang.Object

com.hellosign.sdk.HelloSignClient

public class HelloSignClient
extends Object

You'll need the HelloSignClient to do just about everything, from creating signatures to updating account information. To use this class, instantiate a client with valid credentials like so: HelloSignClient client = new HelloSignClient(user, key); Then, use the client to perform your requests. The client uses the Unirest library to perform its HTTP requests. (http://unirest.io/java.html).

Author:

"Chris Paul ([email protected])"

Field Summary

Fields

Modifier and Type	Field and Description
static String	CLIENT_ID
static String	CLIENT_SECRET
static String	DEFAULT_ENCODING
static String	FILES_FILE_EXT
static String	FILES_FILE_NAME
static String	FINAL_COPY_FILE_EXT
static String	FINAL_COPY_FILE_NAME
static String	OAUTH_CODE
static String	OAUTH_GRANT_TYPE
static String	OAUTH_GRANT_TYPE_AUTHORIZE_CODE
static String	OAUTH_GRANT_TYPE_REFRESH_TOKEN
static String	OAUTH_REFRESH_TOKEN
static String	OAUTH_STATE
static String	TEMPLATE_FILE_EXT
static String	TEMPLATE_FILE_NAME

Constructor Summary

Constructors

Constructor and Description
HelloSignClient(Authentication auth) Create a client with the provided authentication object.
HelloSignClient(String apiKey) Creates a new HelloSign client using your API key.
HelloSignClient(String email, String password) Creates a new HelloSign client using your website account's email address and password.

Method Summary

Modifier and Type	Method and Description
Template	addTemplateUser(String templateId, String idOrEmail) Adds the provided user to the template indicated by the provided template ID.
int	cancelSignatureRequest(String id) Cancels an existing signature request.
Account	createAccount(String email) Creates a new HelloSign account.
Account	createAccount(String email, String password) Deprecated. as of 3.1.1, replaced by createAccount(String)
Account	createAccount(String email, String clientId, String clientSecret) Creates a new HelloSign account and provides OAuth app credentials to automatically generate an OAuth token with the user Account response.
Account	createAccount(String email, String password, String clientId, String clientSecret) Deprecated. as of 3.1.1, replaced by createAccount(String, String, String)
ApiApp	createApiApp(ApiApp app) Creates a new ApiApp using the properties set on the provided ApiApp.
AbstractRequest	createEmbeddedRequest(EmbeddedRequest embeddedReq) Creates a signature request that can be embedded within your website.
TemplateDraft	createEmbeddedTemplateDraft(EmbeddedRequest req) Creates a template draft that can be used for embedded template creation.
Team	createTeam(String teamName) Creates a new team for the current user with the given name.
UnclaimedDraft	createUnclaimedDraft(UnclaimedDraft draft) Creates an unclaimed draft using the provided request draft object.
boolean	deleteApiApp(String clientId) Attempts to delete the API app with the given client ID.
boolean	deleteTemplate(String templateId)
int	destroyTeam() Destroys the current user's team.
Account	getAccount() Returns the current user's account information.
ApiApp	getApiApp(String clientId) Retrieves the API app configuration for the given Client ID.
ApiAppList	getApiApps() Retrieves a paged list of API apps for the authenticated account.
String	getApiUrl()
EmbeddedResponse	getEmbeddedSignUrl(String signatureId) Retrieves the necessary information to build an embedded signature request.
EmbeddedResponse	getEmbeddedTemplateEditUrl(String templateId) Retrieves the necessary information to edit an embedded template.
EmbeddedResponse	getEmbeddedTemplateEditUrl(String templateId, boolean skipSignerRoles, boolean skipSubjectMessage) Retrieves the necessary information to edit an embedded template.
File	getFiles(String requestId) Retrieves a PDF copy of the files associated with a signature request.
File	getFiles(String requestId, String format) Retrieves the file associated with a signature request.
File	getFinalCopy(String requestId) Deprecated. Use getFiles(requestId)
OauthData	getOauthData(String code, String clientId, String secret) Performs an OAuth request and returns the necessary data for authorizing an API application.
OauthData	getOauthData(String code, String clientId, String secret, boolean autoSetRequestToken) Performs an OAuth request and returns the necessary data for authorizing an API application, and will automatically set the access token and code for making authenticated requests with this client.
SignatureRequest	getSignatureRequest(String id) Retrieves a Signature Request with the given ID.
String	getSignatureRequestCancelUrl()
SignatureRequestList	getSignatureRequests() Retrieves the current user's signature requests.
SignatureRequestList	getSignatureRequests(int page) Retrieves a specific page of the current user's signature requests.
String	getSignatureRequestSendUrl()
String	getSignatureRequestUrl()
Team	getTeam() Retrieves the Team for the current user account.
Template	getTemplate(String templateId) Retrieves a specific Template based on the provided Template ID.
File	getTemplateFile(String templateId) Retrieves the PDF file backing the Template specified by the provided Template ID.
TemplateList	getTemplates() Retrieves the templates for the current user account.
TemplateList	getTemplates(int page) Retreives a page of templates for the current user account.
String	getTemplateSignatureRequestUrl()
Team	inviteTeamMember(String idOrEmail) Adds the user to the current user's team.
boolean	isAccountValid(String email) Returns true if an account exists with the provided email address.
boolean	isOnline() Performs a simple call to the HelloSign API to see if it's available with the given credentials.
OauthData	refreshOauthData(String refreshToken) Refreshes the OauthData for this client with the provided refresh token.
Team	removeTeamMember(String idOrEmail) Removes the team member indicated by the user account ID or email address.
Template	removeTemplateUser(String templateId, String idOrEmail) Adds the provided user to the template indicated by the provided template ID.
SignatureRequest	requestEmailReminder(String requestId, String email) Instructs HelloSign to email the given address with a reminder to sign the SignatureRequest referenced by the given request ID.
SignatureRequest	sendSignatureRequest(SignatureRequest req) Sends the provided signature request to HelloSign.
SignatureRequest	sendTemplateSignatureRequest(TemplateSignatureRequest req) Creates a new Signature Request based on the template provided.
void	setAccessToken(String accessToken, String tokenType) Sets the access token for the OAuth user that this client will use to perform requests.
Account	setCallback(String callback) Updates the current user's callback URL.
ApiApp	updateApiApp(ApiApp app) Updates the API app with the given ApiApp object properties.
Team	updateTeamName(String teamName) Updates the current user's team name.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_ENCODING

public static final String DEFAULT_ENCODING

See Also:

Constant Field Values

FINAL_COPY_FILE_NAME

public static final String FINAL_COPY_FILE_NAME

See Also:

Constant Field Values

FINAL_COPY_FILE_EXT

public static final String FINAL_COPY_FILE_EXT

See Also:

Constant Field Values

FILES_FILE_NAME

public static final String FILES_FILE_NAME

See Also:

Constant Field Values

FILES_FILE_EXT

public static final String FILES_FILE_EXT

See Also:

Constant Field Values

TEMPLATE_FILE_NAME

public static final String TEMPLATE_FILE_NAME

See Also:

Constant Field Values

TEMPLATE_FILE_EXT

public static final String TEMPLATE_FILE_EXT

See Also:

Constant Field Values

OAUTH_CODE

public static final String OAUTH_CODE

See Also:

Constant Field Values

OAUTH_STATE

public static final String OAUTH_STATE

See Also:

Constant Field Values

OAUTH_GRANT_TYPE

public static final String OAUTH_GRANT_TYPE

See Also:

Constant Field Values

OAUTH_REFRESH_TOKEN

public static final String OAUTH_REFRESH_TOKEN

See Also:

Constant Field Values

OAUTH_GRANT_TYPE_AUTHORIZE_CODE

public static final String OAUTH_GRANT_TYPE_AUTHORIZE_CODE

See Also:

Constant Field Values

OAUTH_GRANT_TYPE_REFRESH_TOKEN

public static final String OAUTH_GRANT_TYPE_REFRESH_TOKEN

See Also:

Constant Field Values

CLIENT_SECRET

public static final String CLIENT_SECRET

See Also:

Constant Field Values

CLIENT_ID

public static final String CLIENT_ID

See Also:

Constant Field Values

Constructor Detail

HelloSignClient

public HelloSignClient(String apiKey)

Creates a new HelloSign client using your API key. Your HelloSign API key can be found on the Settings page: https://www.hellosign.com/home/myAccount/current_tab/integrations

Parameters:

apiKey - String API key

HelloSignClient

public HelloSignClient(String email,
                       String password)
                throws HelloSignException

Creates a new HelloSign client using your website account's email address and password. Note: This method is not suggested. You're using the API, so sign up for an API key already! https://www.hellosign.com/home/myAccount/current_tab/integrations

Parameters:

email - String email

password - String password

Throws:

HelloSignException - thrown if there is a problem setting the credentials

HelloSignClient

public HelloSignClient(Authentication auth)
                throws HelloSignException

Create a client with the provided authentication object.

Parameters:

auth - HelloSignAuthentication

Throws:

HelloSignException - thrown if the HelloSignAuthentication parameters are invalid or null

Method Detail

getAccount

public Account getAccount()
                   throws HelloSignException

Returns the current user's account information.

Returns:

Account

Throws:

HelloSignException - thrown if there's a problem processing the HTTP request or the JSON response.

isAccountValid

public boolean isAccountValid(String email)
                       throws HelloSignException

Returns true if an account exists with the provided email address. Note this is limited to the visibility of the currently authenticated user.

Parameters:

email - String email address

Returns:

true if the account exists, false otherwise

Throws:

HelloSignException - thrown if there's a problem processing the HTTP request or the JSON response.

setCallback

public Account setCallback(String callback)
                    throws HelloSignException

Updates the current user's callback URL.

Parameters:

callback - String URL

Returns:

Account

Throws:

HelloSignException - thrown if there's a problem processing the HTTP request or the JSON response.

createAccount

public Account createAccount(String email)
                      throws HelloSignException

Creates a new HelloSign account. The user will still need to validate their email address to complete the creation process to set a password. Note: This request does not require authentication, so just performs the basic POST.

Parameters:

email - String New user's email address

Returns:

Account New user's account information

Throws:

HelloSignException - thrown if there's a problem processing the HTTP request or the JSON response.

createAccount

public Account createAccount(String email,
                             String password)
                      throws HelloSignException

Deprecated. as of 3.1.1, replaced by createAccount(String)

Creates a new HelloSign account. The user will still need to validate their email address to complete the creation process. Note: This request does not require authentication, so just performs the basic POST.

Parameters:

email - String New user's email address

password - String New user's password

Returns:

Account New user's account information

Throws:

HelloSignException - thrown if there's a problem processing the HTTP request or the JSON response.

createAccount

public Account createAccount(String email,
                             String clientId,
                             String clientSecret)
                      throws HelloSignException

Creates a new HelloSign account and provides OAuth app credentials to automatically generate an OAuth token with the user Account response.

Parameters:

email - String New user's email address

clientId - String Client ID

clientSecret - String App secret

Returns:

Account New user's account information

Throws:

HelloSignException - thrown if there's a problem processing the HTTP request or the JSON response.

createAccount

public Account createAccount(String email,
                             String password,
                             String clientId,
                             String clientSecret)
                      throws HelloSignException

Deprecated. as of 3.1.1, replaced by createAccount(String, String, String)

Creates a new HelloSign account and provides OAuth app credentials to automatically generate an OAuth token with the user Account response.

Parameters:

email - String New user's email address

password - String New user's password (NOTE: WILL BE IGNORED BY THE API)

clientId - String Client ID

clientSecret - String App secret

Returns:

Account New user's account information

Throws:

HelloSignException - thrown if there's a problem processing the HTTP request or the JSON response.

getOauthData

public OauthData getOauthData(String code,
                              String clientId,
                              String secret)
                       throws HelloSignException

Performs an OAuth request and returns the necessary data for authorizing an API application.

Parameters:

code - String OAuth code

clientId - String OAuth client ID

secret - String OAuth secret

Returns:

OauthData object containing OAuth token details

Throws:

HelloSignException - thrown if there's a problem processing the HTTP request or the JSON response.

getOauthData

public OauthData getOauthData(String code,
                              String clientId,
                              String secret,
                              boolean autoSetRequestToken)
                       throws HelloSignException

Performs an OAuth request and returns the necessary data for authorizing an API application, and will automatically set the access token and code for making authenticated requests with this client.

Parameters:

code - String OAuth code

clientId - String OAuth client ID

secret - String OAuth secret

autoSetRequestToken - true if the token should be immediately applied to this client

Returns:

OauthData object containing OAuth token details

Throws:

HelloSignException - thrown if there's a problem processing the HTTP request or the JSON response.

refreshOauthData

public OauthData refreshOauthData(String refreshToken)
                           throws HelloSignException

Refreshes the OauthData for this client with the provided refresh token.

Parameters:

refreshToken - String

Returns:

OauthData new OAuthData returned from HelloSign

Throws:

HelloSignException - thrown if there's a problem processing the HTTP request or the JSON response.

getTeam

public Team getTeam()
             throws HelloSignException

Retrieves the Team for the current user account.

Returns:

Team

Throws:

HelloSignException - thrown if there's a problem processing the HTTP request or the JSON response.

createTeam

public Team createTeam(String teamName)
                throws HelloSignException

Creates a new team for the current user with the given name.

Parameters:

teamName - String team name

Returns:

Team

Throws:

HelloSignException - thrown if there's a problem processing the HTTP request or the JSON response.

destroyTeam

public int destroyTeam()
                throws HelloSignException

Destroys the current user's team.

Returns:

int HTTP Status

Throws:

HelloSignException - thrown if there's a problem processing the HTTP request or the JSON response.

updateTeamName

public Team updateTeamName(String teamName)
                    throws HelloSignException

Updates the current user's team name.

Parameters:

teamName - String team name

Returns:

Team

Throws:

HelloSignException - thrown if there's a problem processing the HTTP request or the JSON response.

inviteTeamMember

public Team inviteTeamMember(String idOrEmail)
                      throws HelloSignException

Adds the user to the current user's team.

Parameters:

idOrEmail - String new team member's account ID or email address

Returns:

Team

Throws:

HelloSignException - thrown if there's a problem processing the HTTP request or the JSON response.

removeTeamMember

public Team removeTeamMember(String idOrEmail)
                      throws HelloSignException

Removes the team member indicated by the user account ID or email address.

Parameters:

idOrEmail - String removed team member's account ID or email address

Returns:

Team

Throws:

HelloSignException - thrown if there's a problem processing the HTTP request or the JSON response.

getSignatureRequest

public SignatureRequest getSignatureRequest(String id)
                                     throws HelloSignException

Retrieves a Signature Request with the given ID.

Parameters:

id - String signature ID

Returns:

SignatureRequest

Throws:

HelloSignException - thrown if there's a problem processing the HTTP request or the JSON response.

getSignatureRequests

public SignatureRequestList getSignatureRequests()
                                          throws HelloSignException

Retrieves the current user's signature requests. The resulting object represents a paged query result. The page information can be retrieved on from the ListInfo object on the SignatureRequestList.

Returns:

SignatureRequestList

Throws:

HelloSignException - thrown if there's a problem processing the HTTP request or the JSON response.

getSignatureRequests

public SignatureRequestList getSignatureRequests(int page)
                                          throws HelloSignException

Retrieves a specific page of the current user's signature requests.

Parameters:

page - int

Returns:

SignatureRequestList

Throws:

HelloSignException - thrown if there's a problem processing the HTTP request or the JSON response.

sendSignatureRequest

public SignatureRequest sendSignatureRequest(SignatureRequest req)
                                      throws HelloSignException

Sends the provided signature request to HelloSign.

Parameters:

req - SignatureRequest

Returns:

SignatureRequest

Throws:

HelloSignException - thrown if there's a problem processing the HTTP request or the JSON response.

getTemplates

public TemplateList getTemplates()
                          throws HelloSignException

Retrieves the templates for the current user account.

Returns:

TemplateList

Throws:

HelloSignException - thrown if there's a problem processing the HTTP request or the JSON response.

getTemplates

public TemplateList getTemplates(int page)
                          throws HelloSignException

Retreives a page of templates for the current user account.

Parameters:

page - int

Returns:

TemplateList

Throws:

HelloSignException - thrown if there's a problem processing the HTTP request or the JSON response.

getTemplateFile

public File getTemplateFile(String templateId)
                     throws HelloSignException

Retrieves the PDF file backing the Template specified by the provided Template ID.

Parameters:

templateId - String Template ID

Returns:

File PDF file object

Throws:

HelloSignException - thrown if there's a problem processing the HTTP request or the JSON response.

getTemplate

public Template getTemplate(String templateId)
                     throws HelloSignException

Retrieves a specific Template based on the provided Template ID.

Parameters:

templateId - String Template ID

Returns:

Template

Throws:

HelloSignException - thrown if there's a problem processing the HTTP request or the JSON response.

addTemplateUser

public Template addTemplateUser(String templateId,
                                String idOrEmail)
                         throws HelloSignException

Adds the provided user to the template indicated by the provided template ID. The new user can be designated using their account ID or email address.

Parameters:

templateId - String template ID

idOrEmail - String account ID or email address

Returns:

Template

Throws:

HelloSignException - thrown if there's a problem processing the HTTP request or the JSON response.

deleteTemplate

public boolean deleteTemplate(String templateId)
                       throws HelloSignException

Throws:

HelloSignException

removeTemplateUser

public Template removeTemplateUser(String templateId,
                                   String idOrEmail)
                            throws HelloSignException

Adds the provided user to the template indicated by the provided template ID. The new user can be designated using their account ID or email address.

Parameters:

templateId - String template ID

idOrEmail - String account ID or email address

Returns:

Template

Throws:

HelloSignException - thrown if there's a problem processing the HTTP request or the JSON response.

sendTemplateSignatureRequest

public SignatureRequest sendTemplateSignatureRequest(TemplateSignatureRequest req)
                                              throws HelloSignException

Creates a new Signature Request based on the template provided.

Parameters:

req - TemplateSignatureRequest

Returns:

SignatureRequest

Throws:

HelloSignException - thrown if there's a problem processing the HTTP request or the JSON response.

cancelSignatureRequest

public int cancelSignatureRequest(String id)
                           throws HelloSignException

Cancels an existing signature request. If it has been completed, it will delete the signature request from your account.

Parameters:

id - SignatureRequest id

Returns:

HttpStatus code

Throws:

HelloSignException - thrown if there's a problem processing the HTTP request or the JSON response.

requestEmailReminder

public SignatureRequest requestEmailReminder(String requestId,
                                             String email)
                                      throws HelloSignException

Instructs HelloSign to email the given address with a reminder to sign the SignatureRequest referenced by the given request ID. Note: You cannot send a reminder within 1 hours of the last reminder that was sent, manually or automatically.

Parameters:

requestId - String SignatureRequest ID

email - String email

Returns:

SignatureRequest The request to be reminded

Throws:

HelloSignException - thrown if there's a problem processing the HTTP request or the JSON response.

getFinalCopy

public File getFinalCopy(String requestId)
                  throws HelloSignException

Deprecated. Use getFiles(requestId)

Retrieves the final PDF copy of a signature request, if it exists.

Parameters:

requestId - String SignatureRequest ID

Returns:

File final copy file, or null if it does not yet exist

Throws:

HelloSignException - thrown if there's a problem processing the HTTP request or the JSON response.

getFiles

public File getFiles(String requestId)
              throws HelloSignException

Retrieves a PDF copy of the files associated with a signature request.

Parameters:

requestId - String signature ID

Returns:

File PDF file

Throws:

HelloSignException - thrown if there's a problem processing the HTTP request or the JSON response.

getFiles

public File getFiles(String requestId,
                     String format)
              throws HelloSignException

Retrieves the file associated with a signature request.

Parameters:

requestId - String signature ID

format - String format, see SignatureRequest for available types

Returns:

File

Throws:

HelloSignException - thrown if there's a problem processing the HTTP request or the JSON response.

createEmbeddedRequest

public AbstractRequest createEmbeddedRequest(EmbeddedRequest embeddedReq)
                                      throws HelloSignException

Creates a signature request that can be embedded within your website.

Parameters:

embeddedReq - EmbeddedRequest

Returns:

SignatureRequest

Throws:

HelloSignException - thrown if there's a problem processing the HTTP request or the JSON response.

getEmbeddedSignUrl

public EmbeddedResponse getEmbeddedSignUrl(String signatureId)
                                    throws HelloSignException

Retrieves the necessary information to build an embedded signature request.

Parameters:

signatureId - String ID of the signature request to embed

Returns:

EmbeddedResponse

Throws:

HelloSignException - thrown if there's a problem processing the HTTP request or the JSON response.

getEmbeddedTemplateEditUrl

public EmbeddedResponse getEmbeddedTemplateEditUrl(String templateId)
                                            throws HelloSignException

Retrieves the necessary information to edit an embedded template.

Parameters:

templateId - String ID of the signature request to embed

Returns:

EmbeddedResponse

Throws:

HelloSignException - thrown if there's a problem processing the HTTP request or the JSON response.

getEmbeddedTemplateEditUrl

public EmbeddedResponse getEmbeddedTemplateEditUrl(String templateId,
                                                   boolean skipSignerRoles,
                                                   boolean skipSubjectMessage)
                                            throws HelloSignException

Retrieves the necessary information to edit an embedded template.

Parameters:

templateId - String ID of the signature request to embed

skipSignerRoles - true if the edited template should not allow the user to modify the template's signer roles. Defaults to false.

skipSubjectMessage - true if the edited template should not allow the user to modify the template's subject and message. Defaults to false.

Returns:

EmbeddedResponse

Throws:

HelloSignException - thrown if there's a problem processing the HTTP request or the JSON response.

createUnclaimedDraft

public UnclaimedDraft createUnclaimedDraft(UnclaimedDraft draft)
                                    throws HelloSignException

Creates an unclaimed draft using the provided request draft object.

Parameters:

draft - UnclaimedDraft

Returns:

UnclaimedDraft The created draft

Throws:

HelloSignException - thrown if there's a problem processing the HTTP request or the JSON response.

createEmbeddedTemplateDraft

public TemplateDraft createEmbeddedTemplateDraft(EmbeddedRequest req)
                                          throws HelloSignException

Creates a template draft that can be used for embedded template creation.

Parameters:

req - EmbeddedRequest

Returns:

Template the unclaimed template draft

Throws:

HelloSignException - thrown if there's a problem processing the HTTP request or the JSON response.

getApiApp

public ApiApp getApiApp(String clientId)
                 throws HelloSignException

Retrieves the API app configuration for the given Client ID.

Parameters:

clientId - String

Returns:

ApiApp

Throws:

HelloSignException - thrown if there's a problem processing the HTTP request or the JSON response.

getApiApps

public ApiAppList getApiApps()
                      throws HelloSignException

Retrieves a paged list of API apps for the authenticated account.

Returns:

ApiAppList

Throws:

HelloSignException - thrown if there's a problem processing the HTTP request or the JSON response.

createApiApp

public ApiApp createApiApp(ApiApp app)
                    throws HelloSignException

Creates a new ApiApp using the properties set on the provided ApiApp.

Parameters:

app - ApiApp

Returns:

ApiApp newly created ApiApp

Throws:

HelloSignException - thrown if there's a problem processing the HTTP request or the JSON response.

deleteApiApp

public boolean deleteApiApp(String clientId)
                     throws HelloSignException

Attempts to delete the API app with the given client ID.

Parameters:

clientId - String The Client ID of the app that should be deleted.

Returns:

boolean true if the API app was successfully deleted

Throws:

HelloSignException - thrown if there's a problem processing the HTTP request or the JSON response.

updateApiApp

public ApiApp updateApiApp(ApiApp app)
                    throws HelloSignException

Updates the API app with the given ApiApp object properties.

Parameters:

app - ApiApp

Returns:

ApiApp updated ApiApp

Throws:

HelloSignException - thrown if there's a problem processing the HTTP request or the JSON response.

isOnline

public boolean isOnline()

Performs a simple call to the HelloSign API to see if it's available with the given credentials.

Returns:

true if HelloSign is available and the client is online, false otherwise.

setAccessToken

public void setAccessToken(String accessToken,
                           String tokenType)
                    throws HelloSignException

Sets the access token for the OAuth user that this client will use to perform requests.

Parameters:

accessToken - String access token

tokenType - String token type

Throws:

HelloSignException - thrown if there's a problem setting the access token.

getApiUrl

public String getApiUrl()

getSignatureRequestUrl

public String getSignatureRequestUrl()

getSignatureRequestSendUrl

public String getSignatureRequestSendUrl()

getSignatureRequestCancelUrl

public String getSignatureRequestCancelUrl()

getTemplateSignatureRequestUrl

public String getTemplateSignatureRequestUrl()