EchoSign Document API Version 6 Methods

Documentation for latest API Version is also available.

Table of Contents

Document Methods

Status Methods

User Methods

Test Methods

Legend: bold methods are the most commonly used ones; methods with a star were recently added.

sendDocument

View Sample XML: request | response | header

sendDocument is used to send a document out for signature. This is the main entry point into the EchoSign Document API. You will need to provide information about who the sender of the document is, who the recipient(s) are, the file(s) that you'd like to send, and how you want them signed. In addition, there is a variety of other optional flags that control the workflow, described below. To retrieve the signed final document, you may either poll for it using getDocumentInfo or be notified using the CallbackInfo.

sendDocument: Input Parameters

Parameter Name Type Required Default Description
apiKey API_KEY YES N/A The personal API access key that you've been assigned.
senderInfo SenderInfo NO API key user Information about the sender of the agreement. If one is not provided, the agreement is sent from the user for whom the API access key was provisioned. Please see our Single Sign On documentation for more information.
documentCreationInfo DocumentCreationInfo YES N/A Information about the document that you want to send.

sendDocument: Return Value

Parameter Name Type Description
documentKeys DocumentKey[] Array containing one document key which can be used to query status (using getDocumentInfo) and download signed documents (using getLatestDocument).
Back to Top

sendDocumentMegaSign

View Sample XML: request | response | header

sendDocumentMegaSign is used to send a document out for signature to multiple recipients. Each recipient will receive and sign their own copy of the document. You will need to provide information about who the sender of the document is, who the recipients are, the file(s) that you'd like to send, and how you want them signed. In addition, there is a variety of other optional flags that control the workflow, described below. To retrieve the signed final document, you may either poll for it using getDocumentInfo or be notified using the CallbackInfo.

Note: the MegaSign feature is only available for Enterprise EchoSign accounts.

sendDocument: Input Parameters

Parameter Name Type Required Default Description
apiKey API_KEY YES N/A The personal API access key that you've been assigned.
senderInfo SenderInfo NO API key user Information about the sender of the agreement. If one is not provided, the agreement is sent from the user for whom the API access key was provisioned. Please see our Single Sign On documentation for more information.
documentCreationInfo DocumentCreationInfo YES N/A Information about the document that you want to send.

sendDocumentMegaSign: Return Value

Parameter Name Type Description
sendDocumentMegaSignResult sendDocumentMegaSignResult The result of this operation.
Back to Top

Return Object: SendMegaSignDocumentResult

Used in: sendDocumentMegaSign: Return Value

Parameter Name Type Description
success boolean A boolean value indicating whether the result was successful.
errorCode sendDocumentMegaSignErrorCode An error code indicating the reason for failure of the request.
errorMessage String An optional string value describing the reason for the failure of the request
documentKey DocumentKey Document Key of the megaSign master document - which can be used in getMegaSignDocument.
documentKeyArray DocumentKey[] Array of document keys - one for each signer - which can be used to query status (using getDocumentInfo) and download signed documents (using getLatestDocument).
Back to Top

Enumeration: SendDocumentResultErrorCode

Used in: SendDocumentMegaSignResult

Value Description
ERROR See errorMessage for details
Back to Top

Value Object: SenderInfo

Used in: sendDocument and createForm

Parameter Name Type Required Default Description
userKey USER_KEY Either a userKey or an email/password combination is required. If both are passed in, the userKey is used. N/A Unique user identifier - returned by createUser.
email String N/A The email address of the user that's sending the agreement.
password String N/A The password of the user that's sending the agreement.
Back to Top

Value Object: DocumentCreationInfo

Used in: sendDocument

Parameter Name Type Required Default Description
tos String[] YES N/A A list of one or more recipient's email addresses. Each recipient will be sent an email asking them to sign this document. For regular (non-MegaSign) documents, there is a limit of 6 signers for esignature documents and 4 signers for written signature documents. This limit includes the sender if the sender is also a signing party.
ccs String[] NO none A list of one or more email addresses that you want to CC on this transaction. They will each get an email at the beginning and also when the final document is signed, with a copy of the document attached as a PDF.
name String YES N/A The name of the agreement, which will be used to identify it in the emails and on the website.
message String NO none An optional message to the recipient(s) describing to them what is being sent and/or why their signature is required.
fileInfos FileInfo[] YES N/A A list of one or more files (or references to files) that will be sent out for signature. If more than one file is provided, they will be combined into one PDF before being sent out.
signatureType SignatureType YES N/A Selects which type of signature you'd like to request - written or e-signature.
signatureFlow SignatureFlow YES N/A Selects which workflow you'd like to use - whether the signer needs to sign before the recipient, after the recipient, or not at all.
securityOptions SecurityOptions NO none Sets optional secondary security parameters for your document.
externalId ExternalId NO none Not used at this time
reminderFrequency ReminderFrequency NO none Optional parameter which sets how often you'd like the recipient(s) to be reminded to sign this document.
callbackInfo CallbackInfo NO none Sets the callback properties that allows EchoSign to notify you when the agreement has been signed and avoid polling.
Back to Top

Value Object: FileInfo

Used in: DocumentCreationInfo

Parameter Name Type Required Default Description
fileName String YES N/A The original system filename of the document being sent - used to name attachments, and to infer the mime type if one is not explicitly specified.
mimeType String NO inferred from fileName The mime type of the referenced file, used to determine if it can be accepted and to perform any necessary conversion steps.
file base64 encoded content Either a file, url or FORM_KEY must be provided. If more than one is provided the FORM_KEY will take precedence if present, then the URL. Only if neither of the other two are present will the file be used. N/A The raw file content, encoded in base64 form.
url String N/A The url where the raw file content can be retrieved. HTTP authentication is supported using standard embedded syntax - i.e. http://username:password@your.server.com/path/to/file.
formKey FORM_KEY N/A A valid formKey returned by createForm
Back to Top

Enumeration: SignatureType

Used in: DocumentCreationInfo

Value Description
ESIGN Recipient will receive an email asking them to e-sign the document, directly inside a web browser. Both parties will then received the signed document as a PDF.
WRITTEN Recipient will receive an email with your document attached, and a coversheet will be prepended to your document. Recipient will print the document, sign it, and fax it back to the number shown on the generated cover page. Both parties will then received the signed document as a PDF.
Back to Top

Enumeration: SignatureFlow

Used in: DocumentCreationInfo

Value Description
SENDER_SIGNATURE_NOT_REQUIRED Recipient will be the only party asked to sign the document. Both parties will then received the signed document as a PDF.
SENDER_SIGNS_LAST Recipient will be asked to sign the document; afterwards, the sender will be asked to sign. Both parties will then received the signed document as a PDF. This setting is not support for MegaSign documents.
SENDER_SIGNS_FIRST Sender will be asked to sign the document first; afterwards, the recipient will be asked to sign. Both parties will then received the signed document as a PDF. This setting is not support for MegaSign documents.
Back to Top

Value Object: SecurityOptions

Used in: DocumentCreationInfo

Parameter Name Type Required Default Description
password String YES N/A The secondary password that will be used to secure the document. Note that EchoSign will never show this password to anyone, so you will need to separately communicate it to any relevant parties.
protectSignature Boolean At least one of these must be set to true in order for any secondary security to be applied. false If this is set to true, recipients will be required to type in the password before signing.
protectOpen Boolean false If this is set to true, the document will always be encrypted with this password whenever it is emailed to any party, and receiving parties will be required to provide it in order to view the PDF files.
Back to Top

Value Object: ExternalId

Used in: DocumentCreationInfo

Parameter Name Type Required Default Description
namespace String NO none Not used at this time
group String NO none Not used at this time
id String NO none Not used at this time
Back to Top

Enumeration: ReminderFrequency

Used in: DocumentCreationInfo

Value Description
DAILY_UNTIL_SIGNED Recipient(s) will be reminded to sign the document every day, until they have signed it or declined to sign.
WEEKLY_UNTIL_SIGNED Recipient(s) will be reminded to sign the document every week, until they have signed it or declined to sign.
Back to Top

Value Object: CallbackInfo

Used in: DocumentCreationInfo

Parameter Name Type Required Default Description
signedDocumentUrl String NO none The url to which EchoSign will do a HTTP PUT operation with the final signed PDF. HTTP authentication is supported using standard embedded syntax - i.e. http://username:password@your.server.com/path/to/file.
Back to Top

Return Object: DocumentKey

Used in: sendDocument

Parameter Name Type Description
recipientEmail String The email address of the recipient. When a document is simultaneously sent to multiple recipients, this can be used to identify which documentKey corresponds to which recipient.
documentKey DOCUMENT_KEY A unique secure identifier of the document that has been sent out.
Back to Top

getDocumentInfo

View Sample XML: request | response | header

getDocumentInfo can be used to retrieve the up-to-date status of any document that you sent out using sendDocument. At this time, getDocumentInfo can only be used for documents that were sent out using the API, and the apiKey must match the key used to send the document.

getDocumentInfo: Input Parameters

Parameter Name Type Required Default Description
apiKey API_KEY YES N/A The personal API access key that you've been assigned.
documentKey DOCUMENT_KEY YES N/A The document identifier, as provided by sendDocument.

getDocumentInfo: Return Value

Parameter Name Type Description
documentInfo DocumentInfo Information about the specified document.
Back to Top

Return Object: DocumentInfo

Used in: getDocumentInfo

Parameter Name Type Description
status AgreementStatus The current status of the document.
latestDocumentKey VERSION_KEY A key which uniquely identifies the current version of the document - can be used to retrieve the document using getDocumentByVersion.
events DocumentHistoryEvent[] An ordered list of the events in the audit trail of this document.
Back to Top

Enumeration: AgreementStatus

Used in: getDocumentInfo

Value Description
OUT_FOR_SIGNATURE The document is currently waiting for one or more parties to sign it.
SIGNED The document has been signed by all the requested parties. This is a terminal state.
ABORTED The signature workflow has been cancelled by either the sender or the recipient. This is a terminal state.
Back to Top

Return Object: DocumentHistoryEvent

Used in: DocumentInfo

Parameter Name Type Description
date Date The data of the audit event.
description String A text description of the audit event.
documentVersionKey VERSION_KEY A key which uniquely identifies version of the document associated with this audit event - can be used to retrieve the document using getDocumentByVersion.
Back to Top

getLatestDocument

View Sample XML: request | response | header

getLatestDocument can be used to retrieve the latest version of any document that you sent out using sendDocument. At this time, getLatestDocument can only be used for documents that were sent out using the API, and the apiKey must match the key used to send the document.

getLatestDocument: Input Parameters

Parameter Name Type Required Default Description
apiKey API_KEY YES N/A The personal API access key that you've been assigned.
documentKey DOCUMENT_KEY YES N/A The document identifier, as provided by sendDocument.

getLatestDocument: Return Value

Parameter Name Type Description
pdf base64 encoded content The raw file content of the document, provided as a PDF.
Back to Top

getDocumentByVersion

View Sample XML: request | response | header

getDocumentByVersion can be used to retrieve the content of a particular version of a document that was sent out for signature, using a version key returned by getDocumentInfo. At this time, getDocumentByVersion can only be used for documents that were sent out using the API, and the apiKey must match the key used to send the document.

getDocumentByVersion: Input Parameters

Parameter Name Type Required Default Description
apiKey API_KEY YES N/A The personal API access key that you've been assigned.
versionKey VERSION_KEY YES N/A The version identifier, as provided by getDocumentInfo.

getDocumentByVersion: Return Value

Parameter Name Type Description
pdf base64 encoded content The raw file content of this version of the document, provided as a PDF.
Back to Top

getLatestDocumentUrl

View Sample XML: request | response | header

getLatestDocumentUrl can be used to retrieve the URL for the document PDF, using a version key returned by getDocumentInfo. At this time, getLatestImages can only be used for documents that were sent out using the API, and the apiKey must match the key used to send the document.

getLatestDocumentUrl: Input Parameters

Parameter Name Type Required Default Description
apiKey API_KEY YES N/A The personal API access key that you've been assigned.
documentKey DOCUMENT_KEY YES N/A The document identifier, as provided by sendDocument.

getLatestDocumentUrl: Return Value

Parameter Name Type Description
documentUrlResult DocumentUrlResult See DocumentUrlResult
Back to Top

DocumentUrlResult

Used in: getLatestDocumentUrl and getDocumentUrlByVersion
Parameter Name Type Description
isSuccess boolean A boolean value indicating whether the result was successful.
errorCode DocumentUrlResultErrorCode An error code indicating the reason for failure of the request.
errorMessage String An optional string value describing the reason for the failure of the request.
url String The secure URL of the PDF file.

Enumeration: DocumentUrlResultErrorCode

Value Description
INVALID_API_KEY Invalid API Key
INVALID_DOCUMENT_KEY Invalid Document Key
INVALID_VERSION_KEY Invalid Document Key
DOCUMENT_HAS_BEEN_REMOVED The document has previously been removed from the system.

getDocumentUrlByVersion

View Sample XML: request | response | header

getDocumentUrlByVersion can be used to retrieve the URL for the document PDF, using a version key returned by getDocumentInfo. At this time, getImagesByVersion can only be used for documents that were sent out using the API, and the apiKey must match the key used to send the document.

getDocumentUrlByVersion: Input Parameters

Parameter Name Type Required Default Description
apiKey API_KEY YES N/A The personal API access key that you've been assigned.
versionKey VERSION_KEY YES N/A The version identifier, as provided by getDocumentInfo.

getDocumentUrlByVersion: Return Value

Parameter Name Type Description
documentUrlResult DocumentUrlResult See DocumentUrlResult
Back to Top

getLatestImages

View Sample XML: request | response | header

getLatestImages can be used to retrieve the URLs for the images of a document, using a version key returned by getDocumentInfo. At this time, getLatestImages can only be used for documents that were sent out using the API, and the apiKey must match the key used to send the document.

getLatestImages: Input Parameters

Parameter Name Type Required Default Description
apiKey API_KEY YES N/A The personal API access key that you've been assigned.
documentKey DOCUMENT_KEY YES N/A The document identifier, as provided by sendDocument.

getLatestImages: Return Value

Parameter Name Type Description
documentImageList DocumentImageList See DocumentImageList
Back to Top

DocumentImageList

Used in: getLatestImages and getImagesByVersion
Parameter Name Type Description
isSuccess boolean A boolean value indicating whether the result was successful.
errorCode DocumentImageListErrorCode An error code indicating the reason for failure of the request.
errorMessage String An optional string value describing the reason for the failure of the request.
documentImages DocumentImages Array of document images.

Enumeration: DocumemtImageListErrorCode

Value Description
INVALID_API_KEY Invalid API Key
INVALID_DOCUMENT_KEY Invalid Document Key
INVALID_VERSION_KEY Invalid Document Key
DOCUMENT_HAS_BEEN_REMOVED The document has previously been removed from the system.
IMAGES_NOT_AVAILABLE No document images are available.

Document Images

Used in: DocumentImageList
Value Description
getSmallImageUrl URL pointing to small sized image of a page of the document
getMediumImageUrl URL pointing to medium sized image of a page of the document
getLargeImageUrl URL pointing to large sized image of a page of the document

getImagesByVersion

View Sample XML: request | response | header

getImagesByVersion can be used to retrieve the URLs for the images of a document, using a version key returned by getDocumentInfo. At this time, getImagesByVersion can only be used for documents that were sent out using the API, and the apiKey must match the key used to send the document.

getDocumentByVersion: Input Parameters

Parameter Name Type Required Default Description
apiKey API_KEY YES N/A The personal API access key that you've been assigned.
versionKey VERSION_KEY YES N/A The version identifier, as provided by getDocumentInfo.

getImagesByVersion: Return Value

Parameter Name Type Description
documentImageList DocumentImageList See DocumentImageList
Back to Top

cancelDocument

View Sample XML: request | response | header

cancelDocument can be used to abort the signature workflow for any document that you sent out using sendDocument. The sender and the recipient will be notified by email that the transaction has been cancelled, subject to the notification parameters described below. At this time, cancelDocument can only be used for documents that were sent out using the API, and the apiKey must match the key used to send the document.

cancelDocument: Input Parameters

Parameter Name Type Required Default Description
apiKey API_KEY YES N/A The personal API access key that you've been assigned.
documentKey DOCUMENT_KEY YES N/A The document identifier, as provided by sendDocument.
comment String NO none An optional comment describing to the recipient why you are cancelling this transaction.
notifySigner Boolean NO false Sets whether or not you would like the recipient to be notified that the transaction has been cancelled. The notification is mandatory if any party has already signed this document.

cancelDocument: Return Value

Parameter Name Type Description
cancelDocumentResult CancelDocumentResult The result of this operation.
Back to Top

Return Object: CancelDocumentResult

Used in: cancelDocument

Parameter Name Type Description
result CancelDocumentResult.Result A status value showing the result of this operation.
Back to Top

Enumeration: CancelDocumentResult.Result

Used in: CancelDocumentResult

Value Description
CANCELLED The signature transaction was successfully cancelled.
ALREADY_SIGNED The document cannot be cancelled because it has already been signed by all parties.
ALREADY_CANCELLED The document cannot be cancelled because it has already been cancelled by the sender or the recipient.
INVALID_DOCUMENT_KEY The document cannot be cancelled because the provided documentKey is invalid.
INVALID_API_KEY The document cannot be cancelled because the provided apiKey is invalid.
Back to Top

removeDocument

View Sample XML: request | response | header

removeDocument can be used to remove a document from the system. At this time, removeDocument can only be used for documents that were sent out using the API, and the apiKey must match the key used to send the document.

removeDocument: Input Parameters

Parameter Name Type Required Default Description
apiKey API_KEY YES N/A The personal API access key that you've been assigned.
documentKey DOCUMENT_KEY YES N/A The document identifier, as provided by sendDocument.

removeDocument: Return Value

Parameter Name Type Description
removeDocumentResult RemoveDocumentResult The result of this operation.
Back to Top

Return Object: RemoveDocumentResult

Used in: removeDocument: Return Value

Parameter Name Type Description
success boolean A boolean value indicating whether the result was successful.
errorCode RemoveDocumentErrorCode An error code indicating the reason for failure of the request.
errorMessage String An optional string value describing the reason for the failure of the request
Back to Top

Enumeration: DelteDocumentErrorCode

Used in: RemoveDocumentResult

Value Description
INVALID_API_KEY Invalid API Key
INVALID_DOCUMENT_KEY Invalid Document Key
DOCUMENT_HAS_BEEN_REMOVED The document has previously been removed from the system.
DYNAMIC_DOCUMENT_EXPIRATION_NOT_ENABLED The account setting DYNAMIC_DOCUMENT_EXPIRATION_ENABLED is false.
REMOVE_FAILED The system failed to remove the document.
Back to Top

sendReminder

View Sample XML: request | response | header

sendReminder can be used to a real time reminder for any document that you sent out using sendDocument. The party whose turn it is to sign the document (which can either be the sender or the recipient) will receive an email similar to the original request to sign that reminds them that their signature is required. At this time, sendReminder can only be used for documents that were sent out using the API, and the apiKey must match the key used to send the document.

sendReminder: Input Parameters

Parameter Name Type Required Default Description
apiKey API_KEY YES N/A The personal API access key that you've been assigned.
documentKey DOCUMENT_KEY YES N/A The document identifier, as provided by sendDocument.
comment String NO none An optional message to the recipient(s) describing to them what is being sent and/or why their signature is required.

sendReminder: Return Value

Parameter Name Type Description
sendReminderResult SendReminderResult The result of the operation.
Back to Top

Return Object: SendReminderResult

Used in: sendReminder

Parameter Name Type Description
result SendReminderResult.Result A status value showing the result of the operation.
recipientEmail String The email address of the party that was reminded. This may either be the sender or the recipient of the document depending on the selected workflow and on whose turn it was to sign. The reminder will always be sent to whichever party is currently expected to sign a given document.
Back to Top

Enumeration: SendReminderResult.Result

Used in: SendReminderResult

Value Description
REMINDER_SENT The reminder has been successfully sent.
ALREADY_SIGNED The reminder to sign cannot be sent because it has already been signed by all parties.
ALREADY_CANCELLED The reminder to sign cannot be sent because it has already been cancelled by the sender or the recipient.
INVALID_DOCUMENT_KEY The reminder to sign cannot be sent because the provided documentKey is invalid.
INVALID_API_KEY The reminder to sign cannot be sent because the provided apiKey is invalid.
Back to Top

createForm

View Sample XML: request | response | header

createForm: Input Parameters

Parameter Name Type Required Default Description
apiKey API_KEY YES N/A The personal API access key that you've been assigned.
senderInfo SenderInfo NO API key user Information about the creator and owner of the form. If one is not provided, the form belongs to the user for whom the API access key was provisioned. Please see our Single Sign On documentation for more information.
formCreationInfo FormCreationInfo YES N/A Information about the form that you want to create.

createForm: Return Value

Parameter Name Type Description
formCreationResult FormCreationResult The result of this operation

Back to Top



Value Object: FormCreationInfo

Used in: createForm

Parameter Name Type Required Default Description
formType FormType YES none The type of form to create. Either a re-usable document for future transactions, or a re-usable form widget. See documentation for FormType for more information
name String YES none The name for the form
externalId ExternalId No none Not used at this time
fileInfos FileInfo[] YES N/A A list of one or more files (or references to files) that will be used to create the form. If more than one file is provided, they will be combined into one PDF.

Back to Top



Enumeration: FormType

Used in: FormCreationInfo

Value Description
NORMAL Create a normal form. This is a way to store a document that you will be sending repeatedly. You can then use the resulting key in place of a file when calling sendDocument.
WIDGET Create a re-usable form widget. The returned object will contain a piece of Javascript that you can use to embed the form widget on any web page, as well as a URL for an EchoSign hosted version of the widget

Back to Top



Return Object: FormCreationResult

Used in: createForm

Parameter Name Type Description
documentKey DocumentKey A unique secure identifier for the form that has been created. If a NORMAL form was created, this can be used in place of a file or a URL when creating a FileInfo.
widgetCode String Javascript snippet for embedding a WIDGET form in an external page.
widgetUrl String URL for EchoSign hosted version of a WIDGET form.

Back to Top



createUser

View Sample XML: request | response | header

createUser can be used to create a new EchoSign user who can then become the sender of a document used in sendDocument. Note that you do not need to call createUser to create recipient users - EchoSign does not require the recipients to be registered users.

Please see our Single Sign On documentation for additional information about user management.

createUser: Input Parameters

Parameter Name Type Required Default Description
apiKey API_KEY YES N/A The personal API access key that you've been assigned.
userCreationInfo UserCreationInfo YES N/A Personal information about the user that you would like to create.

createUser: Return Value

Parameter Name Type Description
userKey USER_KEY A unique secure identifier of the user that has been created - can be used to send documents on this user's behalf using sendDocument.
Back to Top

Value Object: UserCreationInfo

Used in: createUser

Parameter Name Type Required Default Description
email String YES N/A The email address of the new user.
password String YES N/A The password for the new user.
firstName String YES N/A The first name of the new user.
lastName String YES N/A The last name of the new user.
phone String NO none The phone number of the new user.
company String NO none The company name of the new user.
title String NO none The job title of the new user.
optIn OptIn NO UNKNOWN Whether or not the user has opted in to recieve marketing information from EchoSign and its partners.
customField1 String NO none Custom fields allow additional information to be recorded for new users. These fields are only used as part of customized implementations - please contact EchoSign if you would like to make use of this functionality.
customField2 String NO none
customField3 String NO none
Back to Top

Enumeration: OptIn

Used in: UserCreationInfo

Value Description
YES The user has chosen to receive marketing information from Echosign and its partners.
NO The user has chosen not to receive marketing information from Echosign and its partners.
UNKNOWN It is not known if the user has chosen to receive marketing information from Echosign and its partners.
Back to Top

verifyUser

View Sample XML: request | response | header

verifyUser can be used to confirm that a user can become the sender of a document in sendDocument. If verifyUser shows that a user does not exist, one can be created using createUser. The information passed to verifyUser can either be stored in the caller's database or prompted from the user in real time. Any email/password combination that was used to create a user in createUser will verify successfully unless the user has manually changed their password on the EchoSign web site.

Please see our Single Sign On documentation for additional information about user management.

verifyUser: Input Parameters

Parameter Name Type Required Default Description
apiKey API_KEY YES N/A The personal API access key that you've been assigned.
email String YES N/A The email address of the user that'd you'd like the verify.
password String YES N/A The password of the user that you'd like to verify.

verifyUser: Return Value

Parameter Name Type Description
userVerificationInfo UserVerificationInfo The verification result.
Back to Top

Return Object: UserVerificationInfo

Used in: verifyUser

Parameter Name Type Description
userVerificationStatus UserVerificationStatus The status of the verification operation.
Back to Top

Enumeration: UserVerificationStatus

Used in: UserVerificationInfo

Value Description
VALID User exists; password is correct. This information may now be used to send documents on this user's behalf using sendDcoument
DOES_NOT_EXIST User does not exist. A new user can be created using createUser.
INVALID_PASSWORD The user password is invalid. The user must use the EchoSign web site to reset their password.
UNVERIFIED The user has registered but has not verified their email address. The user must use the EchoSign web site to complete verification.
Back to Top

getDocumentsForUser

View Sample XML: request | response | header

getDocumentsForUser lists agreements visible to the specified user. Please note that the user must be in the same account as the user whose API key is being user to make the request.

getDocumentsForUser: Input Parameters

Parameter Name Type Required Default Description
apiKey API_KEY YES N/A The personal API access key that you've been assigned.
userKey USER_KEY YES N/A The userKey as returned by getUsersInAccount

getDocumentsForUser: Return Value

Parameter Name Type Description
getDocumentsForUserResult GetDocumentsForUserResult The documents result.
Back to Top

Return Object: GetDocumentsForUserResult

Used in: getDocumentsForUser

Parameter Name Type Description
documentListForUser DocumentListItem[] Array of document summary items.
errorCode GetDocumentsForUserResultCode The status of the list operation.
errorMessage String Additional details for errors.
success Boolean True if the operation completed successfuly and false otherwise.
Back to Top

Enumeration: GetDocumentsForUserResultCode

Used in: GetDocumentsForUserResult

Value Description
OK The operation completed successfully.
INVALID_API_KEY The documents cannot be listed because the apiKey provided is not valid.
INVALID_USER_KEY The documents cannot be listed because the userKey provided is not valid.
PERMISSION_DENIED The documents cannot be listed because the userKey specified is that of a user who is not in the same account as that of the user whose apiKey was used to make the request.
EXCEPTION The documents cannot be listed because an exception occurred while processing the request.
MISC_ERROR The documents cannot be listed because an uncategorized error occurred.
Back to Top

Return Object: DocumentListItem

Used in: GetDocumentsForUserResult and GetMegaSignDocumentResult

Parameter Name Type Description
displayDate Date The display date for the agreement.
displayUserInfo DisplayUserInfo The most relevant current user for the agreement, typically the next signer if the agreement is from this user or the sender if received from another user.
documentKey DOCUMENT_KEY A document key which can be used to query status (using getDocumentInfo) and download signed documents (using getLatestDocument).
esign Boolean True if this is an esign document.
megaSign Boolean True if this is a megaSign document. If true, then the list of child documents can be obtained via getMegaSignDocument.
name String The name of the document.
userDocumentStatus DocumentListItemUserDocumentStatus The current status of the document from the user's perspective.
Back to Top

Return Object: DisplayUserInfo

Used in: DocumentListItem

Parameter Name Type Description
company String The display user's company, if available.
fullNameOrEmail String The display user's full name, if available, or email if the name is not available.

Enumeration: DocumentListItemUserDocumentStatus

Used in: DocumentListItem

Value Description
WAITING_FOR_MY_SIGNATURE It is the current user's turn to sign the document.
OUT_FOR_SIGNATURE It is another user's turn to sign the document.
SIGNED The document has been completed.
RECALLED The document was recalled before completion.
WAITING_FOR_FAXIN The current user needs to fax in the original document.
ARCHIVED The document has been archived in the user's account.
FORM The document is a form that can be used to create new documents.
Back to Top

getMegaSignDocument

View Sample XML: request | response | header

getMegaSignDocument lists child documents of the specified master document.

getMegaSignDocument: Input Parameters

Parameter Name Type Required Default Description
apiKey API_KEY YES N/A The personal API access key that you've been assigned.
documentKey DOCUMENT_KEY YES N/A A unique secure identifier of the document that has been sent out (as returned by sendDocumentMegaSign or getDocumentsForUser.)

getMegaSignDocument: Return Value

Parameter Name Type Description
GetMegaSignDocumentResult GetMegaSignDocumentResult The documents result.
Back to Top

Return Object: GetMegaSignDocumentResult

Used in: getMegaSignDocument

Parameter Name Type Description
documents DocumentListItem[] Array of document summary items.
errorCode GetMegaSignDocumentResultCode The status of the list operation.
errorMessage String Additional details for errors.
success Boolean True if the operation completed successfuly and false otherwise.
Back to Top

Enumeration: GetMegaSignDocumentResultCode

Used in: GetMegaSignDocumentResult

Value Description
OK The operation completed successfully.
INVALID_API_KEY The documents cannot be listed because the apiKey provided is not valid.
INVALID_DOCUMENT_KEY The documents cannot be listed because the documentKey provided is not valid.
PERMISSION_DENIED The requesting user does not have permission to view the specified document.
NOT_MEGASIGN The specified document is not a megasign document.
EXPIRED The specified document has expired.
EXCEPTION The documents cannot be listed because an exception occurred while processing the request.
MISC_ERROR The documents cannot be listed because an uncategorized error occurred.
Back to Top

getUsersInAccount

View Sample XML: request | response | header

getUsersInAccount lists all the users who are in the same account as that of the apiKey holder who makes the request. The userKey values obtained can then be used in getDocumentsForUser

getUsersInAccount: Input Parameters

Parameter Name Type Required Default Description
apiKey API_KEY YES N/A The personal API access key that you've been assigned.

getUsersInAccount: Return value

Parameter Name Type Description
getUsersInAccountResult GetUsersInAccountResult The result of the request
Back to Top

Return Object: GetUsersInAccountResult

Parameter Name Type Description
errorCode GetUsersInAccountResultCode The status of the list operation.
errorMessage String Additional details for errors.
success Boolean True if the operation completed successfuly and false otherwise.
userListForAccount UserInfo[] The list of users in the account.
Back to Top

Enumeration: GetUsersInAccountResultCode

Value Description
OK The operation completed successfully.
INVALID_API_KEY The users cannot be listed because the apiKey provided is not valid.
EXCEPTION The users cannot be listed because an exception occurred while processing the request.
MISC_ERROR The users cannot be listed because an uncategorized error occurred while processing the request.
Back to Top

Return Object: UserInfo

Parameter Name Type Description
company String The user's company name
email String The user's email address
fullNameOrEmail String The user's full name, if available; otherwise their email
userKey USER_KEY The userKey value that can be used in getDocumentsForUser

testPing

View Sample XML: request | response | header

testPing is a simple test method that can be used to confirm that your have the URL for a valid EchoSign Document Service gateway, are able to successfully communicate with it using SOAP, and have a valid apiKey. If all these conditions are met, you will receive a friendly success message. If you are not able to call this method successfully, all issues must be resolved before you should attempt calling any of the non-test methods described above.

testPing: Input Parameters

Parameter Name Type Required Default Description
apiKey API_KEY YES N/A The personal API access key that you've been assigned.

testPing: Return Value

Parameter Name Type Description
pong Pong The result of your ping operation.
Back to Top

Return Object: Pong

Used in: testPing

Parameter Name Type Description
message String A friendly message from the server showing that your test succeeded.
Back to Top

testEchoFile

View Sample XML: request | response | header

testEchoFile is a simple test method that can be used to confirm that you are able to successfully transmit and receive binary data by encoding it in base64 form. If you are successful, you will receive back the same binary content that you sent. Do not call this method until you are able to successfully call testPing. If you are not able to call this method successfully, all issues must be resolved before you should attempt calling any of the non-test methods described above.

testEchoFile: Input Parameters

Parameter Name Type Required Default Description
apiKey API_KEY YES N/A The personal API access key that you've been assigned.
file base64 encoded content YES N/A The raw file content, encoded in base64 form.

testEchoFile: Return Value

Parameter Name Type Description
outFile base64 encoded content The raw file content, encoded in base64 form, which is identical to the content that you passed in.
Back to Top

Identifying Keys

This table describes all the unique identifying keys that are used by the EchoSign Document API and which functions expect or return them. Note that for security reasons all keys exist within the namespace of a particular apiKey - i.e. you cannot use one apiKey to create a document and then use a different apiKey to retrieve the status of that document.

Name Type Description Input To Output By
API_KEY String A unique secure identifier that grants a specific user or company access to the API. Please go here to request one or check the value of your existing key. All None
DOCUMENT_KEY String A unique transaction identifier, which remains unchanged from the time you send the document for signature through the time that is signed. getDocumentInfo, getLatestDocument, cancelDocument, sendReminder, getMegaSignDocument DocumentKey
VERSION_KEY String A specific document version identifier, which can be used to retrieve a given snapshot of a particular document. getDocumentByVersion DocumentInfo, DocumentHistoryEvent
USER_KEY String A unique user identifier, which can be used to send documents on behalf of the specified user. SenderInfo, getDocumentsForUser createUser, getUsersInAccount
FORM_KEY String A unique form identifier sendDocument createForm
Back to Top