...

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.

Overview and references

The API is for developers, who want to integrate eSignAnyWhere into their application and for administrators, who want to script interactions with eSignAnyWhere (e.g. user synchronization).

Quick Overview: eSAW uses REST (with JSON) as API. The basic workflow is to upload a document  and then send the envelope with a envelope configuration. Optional, before sending the envelope, it is possible to prepare the envelope to get the workstep configuration for sending the envelope. For more information about the envelope configuration please also have a look at the Envelope Structure. The configuration consists out of the envelope part (workflow configuration) and for each action a definition and a signing configuration (workstep configuration). The workstep configuration is the description (as JSON for REST) of tasks for signer (e.g. Signature Fields, Form-Fields) and additional document configurations.

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.

Resources

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.

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

Changes has been made on api method level as well as the JSON structures and the envelope status values changed.

Overview and references

The API is for developers, who want to integrate eSignAnyWhere into their application and for administrators, who want to script interactions with eSignAnyWhere (e.g. user synchronization).

Quick Overview: eSAW uses REST (with JSON) as API. The basic workflow is to upload a document  and then send the envelope with a envelope configuration. Optional, before sending the envelope, it is possible to prepare the envelope to get the workstep configuration for sending the envelope. For more information about the envelope configuration please also have a look at the Envelope Structure. The configuration consists out of the envelope part (workflow configuration) and for each action a definition and a signing configuration (workstep configuration). The workstep configuration is the description (as JSON for REST) of tasks for signer (e.g. Signature Fields, Form-Fields) and additional document configurations.

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.

Resources

...

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.

Image RemovedImage Added

For string objects, the length is validated. In the following sample, a maximum of 100 characters is checked for the string Name.

Image RemovedImage Added

Ids have a fixed length, therefore the minimum and maximum values are the same:

Image RemovedImage Added

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.

...

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##

...

  "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
      }
    }
  },

...

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

...

For more information please see https://demo.esignanywhere.net/Api/swagger/ui/index#!/Envelope/Envelope_Send section EnvelopeSendActionCallbackSelection

Available Event Types

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/swagger/Draft/Draft_Create

• ##DraftId##
• #Action##
  • draftDiscarded
  • draftSent

Sample:

https://www.mycallback.at?draft=##DraftId##

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/v6/envelope/create

• ##DraftId##
• #Action##
  • draftDiscarded
  • draftSent

Sample:

https://www.mycallback.at?draft=##DraftId##

Error

In general, our REST endpoint returns different HTTP status codes:

...

The request cannot be processed.

...