eSignature API > Tutorial: Hello World

eSignAnyWhere can be easily implemented. This tutorial will show you how to send your first envelope via API and will use this demo document (PDF) via the SOAP webservice of eSignAnyWhere.

For this tutorial you can use your desired programming language (with SOAP support) or any SOAP tool (e.g. SoapUI). Moreover you will need for authorization an active eSignAnyWhere Account (even a trial account will work). If you want to use SoapUI we have a special eSignAnyWhere API with SoapUI Sample for you and if you are using JAVA you may be interested in our Java Library. You might also interested to have a look in the envelope XML guide which explains you more about the XML configuration.

The SOAP endpoint of eSignAnyWhere is: https://www.significant.com/api.asmx

What the tutorial is about

The tutorial will show you the following basic use-case:

First we will have the first API Call and then to implement the above shown use case. Basically you simply upload a document. After the upload you will receive a document id, which you need for creating an envelope with a XML configuration. This configuration contains information about the envelope itself, workflow steps, signer information, policies and many more. After the envelope is created successful the workflow start automatically. The eSignAnyWhere system will use callbacks (you can configure them in the envelope XML configuration) to notify you if the envelope status was changed.

Your first API Call

First we will try the SOAP connection with a version request. So we will call GetVersion_v1(), which doesn’t need any authorization.

The response should be the following:

<apiResult version="2.2.458.6616">
  <baseResult>ok</baseResult>
</apiResult>

Authorization

Almost all API calls are expecting an authorizsationXML. Therefore your organization key and your email-address of a PowerUser is required. You can find the organization key under Settings/Organization/Application in eSignAnyWhere. The email-address and the name of the PowerUser is used for sending the email.

This authorizsation XML has to be encoded via HTML special charaters (“<” in “&lt;” and “>” in “&gt;”). If this encoding is not done you will receive a HTTP 400 Bad Request error. Higher programming languages takes automatically care of the conversion, so just in lower languages it is required (or also SoapUI).

XML:

<authorization>
   <organizationKey>4647688a-xxxx-xxxx-xxxx-xxxxxxxx</organizationKey>
   <userLoginName>your@email.address</userLoginName>
</authorization>

Inline-XML (with HTML special characters):

<authorization>
   <organizationKey>4647688a-xxxx-xxxx-xxxx-xxxxxxxx</organizationKey>
   <userLoginName>your@email.address</userLoginName>
</authorization>

Errors

In case of errors, the error message is part of the response of the SOAP call. In baseResult you see the state of the call (ok/failed) and in errorInfo or okInfo the response. The following you see an authorization error:

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

Upload Document

First we have to upload a document. This will return a DocumentId, to use the document for creating an envelope. Therefore we will use the UploadTemporarySspFile_v1 function. The function requires the authorization and a Base64 encoded file.

For this tutorial we just use a simple PDF document. You can download it here or use your own PDF document.

The uploading call requires the following XML data structure for uploading. Define the file name and the base64 encoded file.

<file>
  <name>eSignAnyWhere_Tutorial.pdf</name>
  <data>##BASE64-FILE-CONTENT##</data>
</file>

This XML also has to be encoded via HTML special charaters (“<” in “&lt;” and “>” in “&gt;”).

The Response after a successfull upload of the file with the document id (SspFileId). The document id you need for creating your first envelope.

<apiResult version="2.2.458.6616">
  <baseResult>ok</baseResult>
  <okInfo>
    <sspFileId>caa5274f-xxxx-xxxx-xxxx-xxxxxxxxxxxx</sspFileId>
  </okInfo>
</apiResult>

After uploading the file it is just temporary on the server. After 10 minutes it will be deleted and you are not able to use it again. The moment you are creating an envelope with the file, it gets the time-to-live of the envelope. Attention: the returned file id is just for creating an envelope. Once the envelope is created, the file id becomes invalid, so for downloading a finished file, you have to retrieve the id from the envelope status (GetEnvelopeById_v1).

Attention: you can not upload more than one file at once.

Get Workstep Configuration

This step is only optional and required if you don’t have a workstep configuration. A workstep configuration is a definition of a signing task for one recipient. So it contains information about signature fields on the document, form-fields, etc. With the new Developer-Feature of eSignAnyWhere 2.6 it is not required anymore.

A workstep configuration is required for each signing step in your workflow. To receive an adhoc workstep configuration you can call GetAdHocWorkstepConfiguration_v1 with an AdHoc-Configuration (to define the AdHoc generation). The default AdHoc configuration of the sample code you can download here (AdHocConfig as ZIP). If you already have your workstep configuration you can skip this step. Moreover you can generate a workstep configuration with the SIGNificant Workstep Designer. The SIGNificant Workstep Designer allows you as a developer to configure a SignAnyWhere workstep, set signature fields and types and many more.

The GetAdHocWorkstepConfiguration_v1 will response the adhoc workstep configuration as result:

<apiResult version="2.2.458.6616">
  <baseResult>ok</baseResult>
  <okInfo>
    <workstepConfiguration>
	  ...
    </workstepConfiguration>
  </okInfo>
</apiResult>

You can download the tutorial AdHocWorkstep here (AdHocWorkstep as ZIP).

Send Envelope

For sending an envelope we are using the SendEnvelope_v1 call. This call requires the authorization, the file id(s) and the envelope configuration. A sample envelope configuration you can download here. You just have to change the recipient email adresses for the Hello World example.

The envelope configuration defines the envelope and the steps in the workflow. For each signing step you need to define a workstep configuration, which defines what the signer has to do in his/her signing task.

<envelope>
   <name>eSignAnyWhere Tutorial</name>
   <eMailSubject>Document of eSignAnyWhere Tutorial</eMailSubject>
   <eMailBody>Dear #RecipientFirstName#! Please sign this tutorial document.</eMailBody>
   <enableReminders>True</enableReminders>
   <firstReminderDayAmount>1</firstReminderDayAmount>
   <recurrentReminderDayAmount>1</recurrentReminderDayAmount>
   <beforeExpirationReminderDayAmount>1</beforeExpirationReminderDayAmount>
   <daysUntilExpire>2</daysUntilExpire>
   <!-- callback to your backend system on a completed envelope 
   <callbackUrl>http://172.16.17.78:57550/default.aspx?EnvelopeId=##EnvelopeId##&amp;myParamForMe=1234</callbackUrl> 
   -->
   <callbackUrl />
   <steps>
      <step>
         <emailBodyExtra />
         <orderIndex>1</orderIndex>
         <recipientType>Signer</recipientType>
         <recipients>
            <recipient>
               <languageCode>en</languageCode>
               <eMail>##SIGNER-EMAIL##</eMail>
               <firstName>Alice</firstName>
               <lastName>Somename</lastName>
               <authentications>
                  <authentication>
                     <method>Pin</method>
                     <parameter>1234</parameter>
                  </authentication>
               </authentications>
            </recipient>
         </recipients>
         <workstepConfiguration>...</workstepConfiguration>
      </step>
      <step>
         <emailBodyExtra />
         <orderIndex>2</orderIndex>
         <recipientType>CC</recipientType>
         <recipients>
            <recipient>
               <languageCode>en</languageCode>
               <eMail>##COPYRECEIVER-MAIL##</eMail>
               <firstName>Charly</firstName>
               <lastName>Randomname</lastName>
            </recipient>
         </recipients>
      </step>
   </steps>
</envelope>

In the sample XML above the workstep configuration is missing and two steps are defined in the workflow. Step 1 as a signing task with PIN authentication and step 2 as a receives copy.

The Workstep Configuration of signer1 is the following:

<workstepConfiguration>
   <WorkstepLabel />
   <SmallTextZoomFactorPercent>100</SmallTextZoomFactorPercent>
   <WorkstepTimeToLiveInMinutes>11520</WorkstepTimeToLiveInMinutes>
   <FinishAction />
   <signatureTemplate>
      <version>1.2.0.2</version>
      <positionUnits>PdfUnits</positionUnits>
      <positionReferenceCorner>Lower_Left</positionReferenceCorner>
      <sig id="93cce567-ae5c-4e98-ac99-9f56ac034250">
         <positionPage>1</positionPage>
         <DocRefNumber>1</DocRefNumber>
         <positionX>80.22857</positionX>
         <positionY>158.8629</positionY>
         <width>171.4286</width>
         <height>68.57143</height>
         <param name="enabled">1</param>
         <param name="completed">0</param>
         <param name="sigType">Picture</param>
         <param name="positioning">onPage</param>
         <param name="allowedCapturingMethods">Click2Sign</param>
      </sig>
   </signatureTemplate>
   <Policy version="1.1.0.0">
      <GeneralPolicies>
         <AllowSaveDocument>1</AllowSaveDocument>
         <AllowSaveAuditTrail>1</AllowSaveAuditTrail>
      </GeneralPolicies>
      <WorkstepTasks SequenceMode="SequenceOnlyRequiredTasks" originalSequenceMode="SequenceOnlyRequiredTasks">
         <Task enabled="1" completed="0" required="1" id="93cce567-ae5c-4e98-ac99-9f56ac034250" displayName="SignField 1" DocRefNumber="1" type="SignField" internalAllConcernedDocRefNumbersList="1" allRequiredFieldsFilledOnWorkstepCreation="0" />
      </WorkstepTasks>
   </Policy>
   <TransactionCodeConfigurations>
      <TransactionCodeConfiguration trConfId="">
         <Message>Please sign the document with the transactionId {tId} with the code: {Token}</Message>
         <hashAlgorithmIdentifier>Sha256</hashAlgorithmIdentifier>
      </TransactionCodeConfiguration>
      <TransactionCodeConfiguration trConfId="Trans1">
         <Message>Please accept the transactionId {tId} with the code: {Token}</Message>
         <hashAlgorithmIdentifier>Sha256</hashAlgorithmIdentifier>
      </TransactionCodeConfiguration>
   </TransactionCodeConfigurations>
</workstepConfiguration>

This is the simplest form of a workstep configuration. With the Developer Feature of eSAW 2.6+ you can download the envelope XML including the workstep configuration of any envelope designed in eSAW UI. Signer 2 only receives a copy, so he doesn’t need to have a workstep configuration.

If the creation of the envelope was successful, you will get the envelope id as response.

<apiResult version="2.2.458.6616">
  <baseResult>ok</baseResult>
  <okInfo>
    <envelopeId>56db6133-xxxx-xxxx-xxxx-xxxxxxxxxxxx</envelopeId>
  </okInfo>
</apiResult>

After the successful creation the enveolpe, it is sent to the first recipient. The envelope id is used for managing the envelopes (send reminders; cancel, delete, reject envelope; …).

Attention: the recipient language must be supported by your organsation (Settings > Localization).

Envelope Status & Callback

The envelope id can be used any time to receive the envelope status. Therefore you simply call the GetEnvelopeById_v1 with the envelope id.

The following is showing the status response:

<apiResult version="2.2.458.6616">
  <baseResult>ok</baseResult>
  <okInfo>
    <envelopeStatus>
      <id>13ad0518-xxxx-xxxx-xxxx-xxxxxxxxxxx</id>
      <name>eSignAnyWhere Tutorial</name>
      <status>Completed</status>
      <sendDate>2017-03-15T12:13:13.453Z</sendDate>
      <expirationDate>2017-03-17T12:13:13.453Z</expirationDate>
      <bulkRecipients>
        <bulkRecipient eMail="">
          <status>Completed</status>
          <recipients>
            <recipient>
              <orderIndex>1</orderIndex>
              <eMail>first.signer@email.com</eMail>
              <status>Signed</status>
              <signedDate>2017-03-15T12:13:42.717Z</signedDate>
              <recipientType>Signer</recipientType>
              <workstepRedirectionUrl></workstepRedirectionUrl>
            </recipient>
            <recipient>
              <orderIndex>2</orderIndex>
              <eMail>cc@email.com</eMail>
              <status>NotSigned</status>
              <signedDate>2017-03-15T12:13:43.183Z</signedDate>
              <recipientType>Cc</recipientType>
              <workstepRedirectionUrl></workstepRedirectionUrl>
            </recipient>
          </recipients>
          <completedDocuments>
            <logDocumentId>52cba71e-xxxx-xxxx-xxxx-xxxxxxxxxxx</logDocumentId>
            <completedDocument>
              <documentId>77851da5-xxxx-xxxx-xxxx-xxxxxxxxxxx</documentId>
              <fileName>eSignAnyWhere_Tutorial.pdf</fileName>
              <fields />
            </completedDocument>
          </completedDocuments>
        </bulkRecipient>
      </bulkRecipients>
    </envelopeStatus>
  </okInfo>
</apiResult>

Callback

The configured callback URL are used to notify your system if the state of an envelope or workstep is changing. So you can track the status of envelopes, without polling the eSignAnyWhere server regulary.

Attention: If you are using an callback URL, which does not return a HTTP 200 code, eSignAnyWhere tries to recall the URL. After some attempts the envelope goes into an error state and will not be finished!

Download a finished document

To download a finished document you simply call the function DownloadCompletedDocument_v1. You have to use the envelope id and the document id to download the file from the server (Attention: just documents of finished envelopes can be downloaded and the document id is different from the uploaded-file-id!). The document id you can receive from the response of the GetEnvelopeById_v1 call.

Download response:

<apiResult version="2.2.458.6616">
  <baseResult>ok</baseResult>
  <okInfo>
    <file>
      <name>eSignAnyWhere_Tutorial.pdf</name>
      <data>##BASE64_FILE##</data>
    </file>
  </okInfo>
</apiResult>

Helpful Features and Resources

In this section you find some helpful features or hints you may use after the tutorial.

• Placeholder for Signaturefields, easy positioning of signature fields in the document.
• Developer FAQ to find answers to open questions. If you still have any question, feel free to contact us.
• The Integration & Use Cases may also be helpful for you to see the basic integration and advanced features & use cases.
• Envelope XML Guide
• SoapUI Tutorial