On this page you will find the eSAW API description. First we start with a basic overview of the API. Before you use the Api Reference, we recommend you to read the API Documenation, to get an overview about our programming interface, data types and basic concepts. If you are looking for examples we recommend the Postman Sample, REST Guide and our Stories and Examples.

Authorization

This section covers a REST-integration. For the authorization you need the OrganizationKey and the UserLoginName of your organization. You can find this two keys in Settings->Organization.

If you are authorized you will get a HTTP/200 Ok info. Otherwise you will get a 401 Unauthorized error.

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.

Envelope Callback

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

  • ##EnvelopeId##
  • ##Action##
    • envelopeFinished : when an envelope was finished (completed or rejected)

Sample:

https://www.mycallback.at?envelope=##EnvelopeId##

Envelope Status Callback

Envelopes status callbacks (“StatusUpdateCallbackUrl”: “”,) are fired, based on envelope events/actions. There are also detailed callbacks available based on events.

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 for that envelope (e.g. internal references). Moreover, on our shared SaaS environments only HTTPS (port 443) callbacks are allowed.

Placehoder for callback URL:

  • ##EnvelopeId##
  • ##Action##
    • workstepFinished : when the workstep was finished
    • workstepRejected : when the workstep was rejected
    • workstepDelegated : whe the workstep was delegated
    • workstepOpened : when the workstep was opened
    • sendSignNotification : when the sign notification was sent
    • envelopeExpired : when the envelope was expired
    • workstepDelegatedSenderActionRequired : when an action from the sender is required because of the delegation

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 for that envelope (e.g. internal references). Moreover, on our shared SaaS environments only HTTPS (port 443) callbacks are allowed.

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

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.xyzmo.com/Api/v4.0/envelope/create

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

Sample:

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

Error

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

  • 200 OK
  • 204 NoContent (response is empty (e.g. download files))
  • 40x return an error code and error info
    • 400 BadRequest (envelope description is incorrect)
    • 401 Unauthorized (User is not authorized)
    • 404 NotFound
    • 415 UnsupportedMediaType
  • or HTTP 500 for generic server errors