...

Introduction

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, 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, v6 Envelope structure and our Stories and Examples.

...

...

...

• Authorization
• UserKey Header Authorization
• Bearer token Authorization
• OrganizationKey and UserLogin Header
  • Creating an organization Key
  • Format Specification

...

• Callback Types
  • Envelope Callback
  • Envelope Status Callback
  • Workstep Event Callbacks
    • Available Event Types
  • Draft Callbacks

...

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.

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 User Guide, Signer Guide and Administration Guide (for on-premise customers) can be also helpful.

General conncepts

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.

Authorization

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. Image Removed

Please see the next sample authorization (Bearer token):

...

Object validation

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 Added

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

Image Added

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

Image 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.

Authorization

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. Image Added

Please see the next sample authorization (Bearer token):

Please see the next sample authorization (api token):

Such an user api token can be created in Settings→API Tokens and Apps; Section "API Tokens".

Tokens created by eSAW are currently 64-digit alphanumeric strings - but the length and set of allowed characters may be changed with future product versions.

Format Specification

 Note that the key can be any 64 digit alphanumeric value; not necessarily following the GUID format! The length and set of allowed characters may be changed with future product versions.

Callbacks

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.

Please see the next sample authorization (api token):

...

Such an user api token can be created in Settings→API Tokens and Apps; Section "API Tokens".

Tokens created by eSAW are currently 64-digit alphanumeric strings - but the length and set of allowed characters may be changed with future product versions.

Format Specification

 Note that the key can be any 64 digit alphanumeric value; not necessarily following the GUID format! The length and set of allowed characters may be changed with future product versions.

Callbacks

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.

...

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

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

Sample:

, via the following call: https://

...

demo.

...

Error

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

...

• 400 BadRequest (envelope description is incorrect)
• 401 Unauthorized (User is not authorized)
• 404 NotFound
• 415 UnsupportedMediaType

esignanywhere.net/Api/swagger/Draft/Draft_Create

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

Sample:

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

...