On this page you will find the eSAW API description and the eSAW UserManagement API description. Morverover we start with a basic overview of the API.
Before you use the API Reference, we recommend you to read the API Documentation, to get an overview about our programming interface, data types and basic concepts. If you are looking for examples, we recommend the Hello World Tutorial, the SoapUI Sample, Postman Sample, REST Guide and our Stories and Examples (with all XML calls).
<apiResult version="1.2.3.4"> <baseResult>ok</baseResult> <okInfo> <!-- actual method result --> </okInfo> </apiResult> |
<apiResult version="1.2.3.4"> <baseResult>failed</baseResult> <errorInfo> <error>ERR....</error> <errorMsg>error message</errorMsg> </errorInfo> </apiResult> |
SOAP uses XML, which have to be encoded via HTML special charaters (“<” in “&lt;” and “>” in “&gt;”). Higher programming languages takes automatically care of the conversion, so just in lower languages it is required (or also SoapUI). If this encoding is not done you will receive a HTTP 400 Bad Request error.
REST uses JSON. We recommend to have a look in the sample code first, otherwise Swagger UI is available for integration, which is available under /api (demo.xyzmo.com/api or esignanywhere.net/api).
We recommend to have a look into the Hello World Tutorial, the SoapUI Sample (SOAP), Postman Sample (REST) and our Stories and Examples (with all XML calls). Moreover our C# Sample Code (depricated, SOAP-only) contains helpful integrations. |
For authentication, you’ll need an api token. You can find this information in Settings / Api Tokens and Apps. Note that all API methods require authentication. Start with the Hello World, SoapUI Tutorial or Postman Tutorial (REST) and you might have a look in the envelope XML guide. Please note, that the email is automatically the user, who sends the envelope.
This section covers a SOAP-integration. The REST/JSON API is similar and you might have a look into Swagger and the Postman Sample. As written in the API Documentation, you have to access API calls with an authorization information.
<authorization> <apiToken >hizit4enf8ellb6b5h12345bgt8mzf1abcedf27jys91hetvesabcd9fdb312348bk</apiToken > </authorization>
The API token is a user specific secret which should not be shared with other users. We recommend to create different API keys for different application integrations, to avoid configuring the same key in various integration systems. This allows, e.g. in case of sharing a key by mistake, to disable one key while keeping other integrations working with their existing configuration. Note that the Authorization XML is passed on as string parameter, not as directly embedded XML – so encode the the < with < and > with > when directly testing e.g. in a SOAP test environment (no extra encoding required when your SOAP library encodes the parameters automatically, e.g. in .NET or Java)
You can also authorize with the organizationKey and the userLoginName. Please see the following configuration: Note: The organizationKey can also be found in Settings / Api Tokens and Apps
|
The API allows the definition of several callbacks.
Please note, that only the envelope callback (directly from eSignAnyWhere) is fired, when the envelope is in a final state. The status update callback is fired by a sub-component and you may require to wait a post-processing time that the envelope reaches its final state.
Note: Please send back the HTTP 200 immediately! If you are not returning the HTTP 200 immediately, eSignAnyWhere tries to recall the URL.
Attention: After some attempts the envelope will not be finished!
Please note the following information which applies to all callbacks: |
This is the basic callback (<CallbackUrl />), which is fired if the envelope reaches a final state (completed, rejected). If you integrate eSAW, please have a look at the Envelope Status Callback (directly below documented), because it might deliver more details about the envelope and might so be more useful for integrating.
Placehoder
Sample:
https://www.mycallback.at?envelope=##EnvelopeId##
Envelopes status callbacks (<statusUpdateCallbackUrl />) are fired, based on envelope events/actions. There are also detailed callbacks available based on events (see this guide).
Placehoder for callback URL:
Sample:
https://www.mycallback.at?envelope=##EnvelopeId##&action=##Action##
Sample with custom parameter “internalid“:
https://www.mycallback.at?envelope=##EnvelopeId##&action=##Action##&internalid=1234
Draft callbacks are fired, if a draft is used or deleted. The draft callback is set in the DraftOptionsXML (<AfterSendCallbackUrl />) via CreateDraft_v1.
Sample:
https://www.mycallback.at?draft=##DraftId##
The SOAP response is a XML datastructure with the state of the response and the response itself. In baseResult
you see the state of the call (ok/failed) and in errorInfo
or okInfo
the response of your request. In case of an error a helpful message is in the errorInfo
. A list of error codes is also available.
In general, our SOAP endpoint return a HTTP success (HTTP/200) even in case of errors, when your call reached the server. The response then has baseResult false, and contains an errorInfo with error (the error code) and errorMsg (human readable error information).
Example:
<?xml version="1.0" encoding="UTF-8"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <soap:Body> <GetAdHocWorkstepConfiguration_v1Response xmlns="http://www.eSignAnyWhere.com/"> <GetAdHocWorkstepConfiguration_v1Result><![CDATA[<apiResult version="2.1.260.5831"> <baseResult>failed</baseResult> <errorInfo> <error>ERR0009</error> <errorMsg>ERR0009: Authorization of user '...' failed</errorMsg> </errorInfo> </apiResult>]]></GetAdHocWorkstepConfiguration_v1Result> </GetAdHocWorkstepConfiguration_v1Response> </soap:Body> </soap:Envelope> |
or:
<apiResult version="2.2.458.6616"> <baseResult>failed</baseResult> <errorInfo> <error>ERR0011</error> <errorMsg>ERR0011: Parameter apiAuthorizationXml is incorrect: Failed to parse</errorMsg> </errorInfo> </apiResult> |
Some reasons for errors:
SOAP API endpoint is https://www.significant.com/api.asmx
WSDL can be found here: https://www.significant.com/api.asmx?WSDL
An envelope can consist of multiple documents and can contain multiple recipients for signing (steps). Your backend application will provide the documents for the envelope and the configuration of the workflow and worksteps. Once the envelope has been completed or rejected, your backend will be notified from eSignAnyWhere about this (callback). Therefore you can provide a callback url, so you don’t need to poll the eSAW system.
Upload all documents for this envelope (UploadTemporarySspFile_v1
)
Optional: Analyze all documents to get a default configuration. (GetAdHocWorkstepConfiguration_v1
)
Optional: Prepare configuration for every signing step in the envelope, by adjusting the xml accordingly.
Start the workflow of the envelope by providing the general configuration of the envelope and the configuration for every step (SendEnvelope_v1
)
Upload all documents for this envelope (UploadTemporarySspFile_v1
)
Create the draft by providing the general configuration of the envelope (CreateDraft_v1
)
You can redirect the user to the designer of eSignAnyWhere to manually position and assign fields for the recipients pf this envelope.
Once you get the notification from eSignAnyWhere that an envelope has been completed, you can download the signed documents and the log of the envelope.
Check the status of that Envelope, to be sure it is completed and not rejected. (GetEnvelopeById_v1
)
Download all the signed documents and the envelope log. (DownloadCompletedDocument_v1
)
SendReminders_v1
: Send reminders to all recipients that currently can sign the envelopeCancelEnvelope_v1
: Cancels the envelopeDeleteEnvelope_v1
: Delets an envelope or a draft of an envelopeRestartEnvelope_v1
: Restarts an expired envelope