Info | ||
---|---|---|
| ||
Please note that this documentation and the links refer to the api v6. For more information please see the migration guide and the documentation related to v5. |
Introduction
On this page you will find the eSAW API description. First we start with a basic overview of the API. If you are looking for examples we recommend the Postman Sample, Envelope structure and our Stories and Examples.
Table of Contents | ||
---|---|---|
|
Principles of Api v6
Detailed information about api v6 can be found here: migration guide.
...
- Only HTTP GET and POST
...
...
Info |
---|
REST API /v3 and /v4 DEPRECATION: The 23.76 (published March 2024) will be the last LTS version that includes these API versions. By early June 2024, the REST API routes to v3/v4 will be deactivated on DEMO. Early December 2024, the REST API routes to v3/v4 will be removed from feature stream releases. Note that there is no date communicated yet to discontinue REST APIv5 (and where v5 refers to v4 routes, these will still remain); however we recommend to use the /v6 API specification already. |
Introduction
On this page you will find the eSAW API description. First we start with a basic overview of the API. If you are looking for examples we recommend the Postman Sample, Envelope structure and our Stories and Examples.
Table of Contents | ||
---|---|---|
|
Principles of Api v6
Detailed information about all changes between api v5 and api v6 can be found here: migration guide.
- Reduced HTTP verbs
- Only HTTP GET and POST
- Consistent naming and symmetric structures within api v6
- Consistency between Web User Interface (WebUI) and api v6 in features but also naming
- Positive wording (e.g. prevent sharing with team changed to share with team)
- Simplified terminology and structures
- No abstract types any more
...
The easiest way to start is enabling the DeveloperMode for a user. As developer (and power user) you can send envelopes via eSignAnywhere in the UI and download the complete envelope configuration (including the workstep configurations). So eSAW can be a seen as configuration designer, where you can easily prepare the envelope configuration. After you downloaded the configuration you just have to replace the recipient information and configuration.
...
REST API Reference (Swagger) | >= 3.1 | | https://demo.esignanywhere.net/Api |
REST tutorials | This turorials help getting familiar with the API technology and the most common tools to do first tests of API calls already before implementing your own integration code. visit REST tutorial using Postman |
Tutorial: Hello World* | This tutorial allows to dig into the API integration of eSignAnyWhere a bit deeper. It focuses on audience already familiar with tools to run API calls, such as Postman or SoapUI. |
Developer mode* | visit developer mode |
Sample Code in Java | Here you can find the java sample: Download. (Contains example with REST, developed with JavaSE-12) |
SignAnyWhere Viewer 2019 Redesign | visit SignAnyWhere Viewer 2019 Information |
SignAnyWhere Viewer Extended Customization | visit SignAnyWhere Viewer Extended Customization |
Integration & Use Cases | visit Integration & Use Cases |
Developer FAQ | visit Developer FAQ |
eSAW Error Codes | visit eSAW Error Codes |
* Recommended
The User Guide, Signer Guide and Administration Guide (for on-premise customers) can be also helpful.
...
String and array objects are validated. If hovering over an object in the model section on e.g. https://demo.esignanywhere.net/Api/swagger/ui/index you can see which validation is performed. In the following sample the validation for the Documents array is such that at least one document must be added and maximum of 50 documents are allowed.
For string objects, the length is validated. In the following sample, a maximum of 100 characters is checked for the string Name.
Ids have a fixed length, therefore the minimum and maximum values are the same:
Authorization
This section covers the authorization options for REST-API integrations. For the authorization you have different options with REST API; as described in the next chapters. If you are authorized you will get a HTTP/200 Ok info. Otherwise you will get a 401 Unauthorized error.
...
We recommend to use user-specific API tokens. Therefore, each user can create several tokens for different application integrations. The apiToken has to be provided as HTTP Header.
Please see the next sample authorization (Bearer token):
Key | Value |
---|---|
"Authorization" | e.g. "Bearer asdfngtmvv8pfmsuaxpzz85zux3e63dd9zttrwitx9mln6qka6tds83du3p3lroe" |
Please see the next sample authorization (api token):
Key | Value |
---|---|
"ApiToken" | "asdfngtmvv8pfmsuaxpzz85zux3e63dd9zttrwitx9mln6qka6tds83du3p3lroe" |
...
Consider, that our system expects the full callback url, including the parameter list you expect, with the placeholders that should be replaced by values at runtime. You can also add your own paramter parameter for that envelope (e.g. internal references). Moreover, on our shared SaaS environments only HTTPS callbacks (port 443, and 1025-65535) callbacks are allowed.
Placehoder for callback URL:
...
Consider, that our system expects the full callback url, including the parameter list you expect, with the placeholders that should be replaced by values at runtime. You can also add your own paramter parameter for that envelope (e.g. internal references). Moreover, on our shared SaaS environments only HTTPS callbacks (port 443, and 1025-65535) callbacks are allowed.
Sample:
https://www.mycallback.at?envelope=##EnvelopeId##&action=##Action##
...
Code Block | ||||
---|---|---|---|---|
| ||||
"CallbackConfiguration": { "CallbackUrl": "string", "StatusUpdateCallbackUrl": "string", "StepActionCallbackConfigurationActivityActionCallbackConfiguration": { "Url": "string", "ActionCallbackSelection": { "ConfirmTransactionCode": true, "DefaultEventType": true, "AgreementAccepted": true, "AgreementRejected": true, "RequestPrepareAuthenticationInformationSuccess": true, "PrepareAuthenticationSuccess": true, "AuthenticationFailed": true, "AuthenticationRejected": true, "AuthenticationSuccess": true, "ReAuthenticationFailed": true, "AuditTrailRequested": true, "AuditTrailXmlRequested": true, "CalledPage": true, "WhoIsInformation": true, "DocumentDownloaded": true, "FlattenedDocumentDownloaded": true, "AddedAnnotation": true, "AddedAttachment": true, "AppendedDocument": true, "FormsFilled": true, "ConfirmReading": true, "PageViewChanged": true, "SendTransactionCode": true, "PrepareSignWorkstepDocument": true, "SignWorkstepDocument": true, "UndoAction": true, "WorkstepCreated": true, "WorkstepFinished": true, "WorkstepRejected": true, "DisablePolicyAndValidityChecks": true, "EnablePolicyAndValidityChecks": true, "AppendFileToWorkstep": true, "AppendTasksToWorkstep": true, "SetOptionalDocumentState": true, "PreparePayloadForBatch": true } } }, |
Please note that if all event types are disabled the URL which was configured in the configuration will not get any callbacks.
These events are fired by the Workstep Controller (internal component) and are fired before the data in eSAW is complete updated (some post-processing is required). Therefore this event callbacks are used only in rare integrations.
Available Event Types
...
PreparePayloadForBatch": true
}
}
}, |
Please note that if all event types are disabled the URL which was configured in the configuration will not get any callbacks.
These events are fired by the Workstep Controller (internal component) and are fired before the data in eSAW is complete updated (some post-processing is required). Therefore this event callbacks are used only in rare integrations. For more information please see https://demo.esignanywhere.net/Api/swagger/ui/index#!/Envelope/Envelope_Send section EnvelopeSendActionCallbackSelection
Available Event Types
Type | Description |
---|---|
ConfirmTransactionCode | A transaction code was sent |
AgreementAccepted | The user accepted the agreement |
AgreementRejected | The user rejected the agreement |
PrepareAuthenticationSuccess | The prepare authentication process succeeded |
AuthenticationFailed | The user failed to authenticate |
AuthenticationSuccess | The user succeeded to authenticate |
AuditTrailRequested | The audittrail was requested |
AuditTrailXmlRequested | The audittrail XML was requested |
CalledPage | The viewer site was requested |
DocumentDownloaded | The document download was requested |
FlattenedDocumentDownloaded | The flattened document download was requested |
AddedAnnotation | An annotation was added |
AddedAttachment | An attachment was added |
AppendedDocument | A document was appended |
FormsFilled | A form field was filled |
ConfirmReading | A reading task was completed |
PageViewChanged | Note: This event is only used for the audit trail, no notification is sent to the configured URL. The user changed the page view (e.g. by scrolling through the document). |
SendTransactionCode | This event is raised, when a TransactionCode for a signature with type TransactionCode has been sent using the IdentityServer or the TransactionCodeSenderPlugin |
PrepareSignWorkstepDocument | A signature is prepared for signing |
SignWorkstepDocument | Try to sign a signature |
UndoAction | An action was undone |
WorkstepCreated | A workstep was created |
WorkstepFinished | A workstep was finished |
WorkstepRejected | A workstep was rejected |
DisablePolicyAndValidityChecks | The policy and validity checks have been disabled. |
EnablePolicyAndValidityChecks | The policy and validity checks have been enabled. |
AppendFileToWorkstep | A file was appended to the workstep |
AppendTasksToWorkstep | A task was added to the workstep |
SetOptionalDocumentState | A optional document became either active or inactive |
PreparePayloadForBatch | The payload is getting prepared for batch signing |
Draft Callbacks
Draft callbacks are fired, if a draft is used or deleted. The draft callback is set in the “CreateDraftOptions” (“AfterSendCallbackUrl”: “”), via the following call: https://demo.esignanywhere.net/Api/v6swagger/envelopeDraft/createDraft_Create
- ##DraftId##
- #Action##
- draftDiscarded
- draftSent
...