eSignature API > Developer FAQ

Developer FAQ

How to use the SOAP or REST Interface, Testing and Tools?

eSignAnyWhere offers you an SOAP and a REST interface. It uses authentication and XML for the datastructures. See our API documentation for the basic information about our interfaces. Most programming languages offer you simple SOAP/REST interfaces moreover for the beginning you may start with SoapUI, a webservice testing tool.

Customization: How can i customize the eSignAnyWhere UI?

There are two possibilities to customize the UI

  • eSignAnyWhere UI for Signers: you can customize it by changing the template
  • eSignAnyWhere UI for Users (Backoffice): this can just be done in a private cloud instance or on premise. For more information contact us.

Customization: How can i customize emails and languages?

You can configure email templates and languages for your eSignAnyWhere signers. It may also helpful if you have a look in the user guide settings section.

API: Where do i find a guide for the envelope and workstep XML?

There is an envelope XML guide available.

API: Can I prefill PDF Forms?

You can prefill PDF form field with values via API. The following API methods are supported:

  • SendEnvelope_v1
  • SendEnvelopeFromTemplate_v1
  • CreateDraft_v1
  • CreateDraftFromTemplate_v1

XML Configuration for prefill PDF forms:

<envelope>
   ...
   <overrideFormFieldValues>
      <document docRef="1">
         <textBox name="formId">
            <value>textBoxValue</value>
         </textBox>
         <listBox name="formId">
            <selectedItems>
               <selectedItemId>selectedItem1</selectedItemId>
               <selectedItemId>selectedItem2</selectedItemId>
            </selectedItems>
         </listBox>
         <radioButtonGroup name="formId">
            <selectedItemId>selectedItem</selectedItemId>
         </radioButtonGroup>
         <checkBox name="formId">
            <isChecked>true|false|0|1</isChecked>
         </checkBox>
         <comboBox name="formId">
            <value>comboBoxValue</value>
         </comboBox>
      </document>
   </overrideFormFieldValues>
   ...
</envelope>

API / Integration: How do I embed eSignAnyWhere Designer in my application?

First you have to create a draft (CreateDraft_v1) and configure the option to allow an external designer (allowAgentRedirect).

XML Configuration

<draftOptions>
	...
	<allowAgentRedirect>true</allowAgentRedirect>
	<iFrameWhiteList>http://172.16.17.256;http://foo.org</iFrameWhiteList>
	...
</draftOptions>

The option allowAgentRedirect enables an anonymous designer integration (without eSignAnyWhere Login) and iFrameWhiteList extends the HTTP header with a list to integrate in your web application or portal (via X-FRAME-OPTIONS).

The designer can be embedded by modifing the following string:

http://www.significant.com/AgentRedirect/index?draftid=#envelopeid#

If the draft is finished you can start the envelope.

API / Integration: Suppress sending email for recipient

If you don’t want to send an email to a specific recipient, you just have to add the following configuration to the envelope XML (<disableEmail>True</disableEmail>):

Simple Example:

...
<recipient>
	<languageCode>en</languageCode>
	<eMail>recipient@email.com</eMail>
	<firstName>Firstname</firstName>
	<lastName>Lastname</lastName>
	...
	<disableEmail>True</disableEmail>
	...
	<!-- optional authentication methods for this recipient -->
</recipient>
...

API / Integration: How often is the callback URL retried?

eSignAnyWhere it calling the Callback URL 30 times. With the timeout this should be enough to recover if the called system is down for a few minutes.

API / Integration: How to modify SMS OTP message (language and content)?

You can modify the message and also the language of the SMS OTP sent via API. The easiest way is to call the GetAdHocWorkstepConfiguration_v1 to recive a default workstep for the document or you can modify it directly via API (see example below).

Three types can be defined:

  • smsAuthTransactionCodeId (SMS Authentication Message)
  • disposableCertificateEnrolAndSignSmsText (Disposable Certificate Message)
  • remoteCertificateSignSmsText (Remote Certificate Message)

As tag {tId} (Transaction ID) and {Token} (Token) must be defined in the message. If you do not define a language attribute, this will be used as fallback or specified language or recipient does not exists.

  
  <TransactionCodeConfigurations>
    <!--Single TransactionCodeConfiguration.-->
    <TransactionCodeConfiguration trConfId="smsAuthTransactionCodeId">
      <!--Message used to send a transaction code to the client. The message has to contain the placeholder '{tId}' for the transactionId and the placeholder '{Token}' for the token.-->
      <Message>Please authenticate yourself for the access to the envelope with the transactionId {tId}. Your code is: {Token}</Message>
      <hashAlgorithmIdentifier>Sha256</hashAlgorithmIdentifier>
    </TransactionCodeConfiguration>
    <TransactionCodeConfiguration trConfId="smsAuthTransactionCodeId" language="en">
      <Message>Please authenticate yourself for the access to the envelope with the transactionId {tId}. Your code is: {Token}</Message>
      <hashAlgorithmIdentifier>Sha256</hashAlgorithmIdentifier>
    </TransactionCodeConfiguration>
    <TransactionCodeConfiguration trConfId="smsAuthTransactionCodeId" language="it">
      <Message>Con riferimento alla transazione {tId}, per autenticarsi si prega di inserire il seguente CODICE {Token}</Message>
      <hashAlgorithmIdentifier>Sha256</hashAlgorithmIdentifier>
    </TransactionCodeConfiguration>
    <TransactionCodeConfiguration trConfId="disposableCertificateEnrolAndSignSmsText">
      <Message>Please confirm the issuance of your disposable certificate and signature, referenced by transactionId {tId}, with the OTP: </Message>
      <hashAlgorithmIdentifier>Sha256</hashAlgorithmIdentifier>
    </TransactionCodeConfiguration>
    <TransactionCodeConfiguration trConfId="disposableCertificateEnrolAndSignSmsText" language="en">
      <Message>Please confirm the issuance of your disposable certificate and signature, referenced by transactionId {tId}, with the OTP: </Message>
      <hashAlgorithmIdentifier>Sha256</hashAlgorithmIdentifier>
    </TransactionCodeConfiguration>
    <TransactionCodeConfiguration trConfId="disposableCertificateEnrolAndSignSmsText" language="it">
      <Message>Conferma l'emissione del tuo certificato disposable, con riferimento alla transazione {tId}, e della firma con l´OTP </Message>
      <hashAlgorithmIdentifier>Sha256</hashAlgorithmIdentifier>
    </TransactionCodeConfiguration>
    <TransactionCodeConfiguration trConfId="remoteCertificateSignSmsText">
      <Message>Please sign the document, referenced by transactionId {tId}, using the OTP: </Message>
      <hashAlgorithmIdentifier>Sha256</hashAlgorithmIdentifier>
    </TransactionCodeConfiguration>
    <TransactionCodeConfiguration trConfId="remoteCertificateSignSmsText" language="en">
      <Message>Please sign the document, referenced by transactionId {tId}, using the OTP: </Message>
      <hashAlgorithmIdentifier>Sha256</hashAlgorithmIdentifier>
    </TransactionCodeConfiguration>
    <TransactionCodeConfiguration trConfId="remoteCertificateSignSmsText" language="it">
      <Message>Firma il documento, con riferimento alla transazione {tId}, usando l´OTP </Message>
      <hashAlgorithmIdentifier>Sha256</hashAlgorithmIdentifier>
    </TransactionCodeConfiguration>
  </TransactionCodeConfigurations>

API / Integration: Envelope is finished, but status is still "in Progress".

If you have a finished envelope (all recipients finished) and the state of the evelope is still “in Progress”, the reason could be the post processing (the callback). The callback expects a HTTP 200 and if an error is retured it tries to call the callback after some time again (up to 30 times). This could delay the “finished” or “error” of the envelope.

API / Integration: Envelope is in state "started", but the "workstepRedirectionUrl" is empty

The problem is, that the envelope is not yet in the correct status.
The current status is “Started”. This means, that the link for the first recipient is not yet being created.

You have to wait until the status is “InProgress”.

Another option would be to either…

  • set “suppressEmails” on the recipient
  • or to check “Prevent emails from being sent :” on the organization (using the Admin Web site)

Then the link will be generated immediately when calling SendEnvelope_v1.

If you use regular notifications (emails), the link is sent to the recipient as soon as the Workstep is ready.

API / Integration: Set a reading task, so that the signer has to confirm the reading

You can define a reading task, so that the signer has to confirm the reading of the envelope. Details about the configuration you find in the Reading Task Guide.

API/Integration: Can i store META DATA in the envelopes?

Yes, you can store your own meta data in the envelopes.

<envelope>
   <metaData>
      <element>custom data</element>
   </metaData>
</envelope>

The metaData element allows you to store additional, non-eSAW-data (e.g. for archiving) directly in the envelope. You can retrieve this information via getEnvelopeById call. An example of metaData is to store data for the archiving system in the envelope. The callback-integrating solution then can download the files (PDF & Audit-Trail) and store them directly in the archive.

API/Integration: What envelope status are available?

The status of an envelope can be:

  • Draft
  • Started
  • InProgress
  • Canceled
  • Completed
  • Expired
  • Rejected
  • Template
  • CompletedWithWarnings

Integration: How do I use SIGNificant Apps with eSignAnyWhere or catch the WorkstepId?

eSAW supports to send out links for the SIGNificant products automatically via notifications. Therefore you just have to add to the recipient configuration (XML) the following parameters:

<envelope>
  <steps>
    <step>
      <recipients>
        <recipient>
          <addAndroidAppLink>0</addAndroidAppLink> <!-- 0 or 1 -->
          <addIosAppLink>0</addIosAppLink> <!-- 0 or 1 -->
          <addWindowsAppLink>0</addWindowsAppLink> <!-- 0 or 1 -->
        </recipient>
      </recipients>
    </step>
  </steps>
</envelope>

Otherwise you can connect one workstep of eSignAnyWhere with one of the SIGNificant Apps. First you call the GetEnvelopeById_v1 with the envelopeID you got in sendEnvelope_v1. In the result you will find the workstepRedirectionURL. This URL forwards the SignAnywhere Viewer (Web-Client), but with the additional parameter &responseType=returnWorkstepId it returns the workstepId. Example:

https://demo.xyzmo.com/workstepredirector/sign?identifier=8WNDxmUVr5V/aV1AAN49xjKuVsHMQEIQVuM/ktLNw1jOfWgaovF2mDg3uW9JJbp5Q/k7Yz92eoo=&responseType=returnWorkstepId

With this WorkstepId you can now connect the SIGNificant product to the document. If the document is finsihed the workflow continues automatically.

Other parameters are:

  • responseType=redirectToViewer – redirects to SAW Viewer (default)
  • responseType=redirectToAndroidApp – redirects to Android App
  • responseType=redirectToIOsApp – redirects to iOS App
  • responseType=redirectToWindowsApp – redirects to Windows App
  • responseType=returnWorkstepId – returns the WorkstepId for other integration types

Integration: custom callbacks on specific events

If you want to get a callback on specific events, e.g. when a signer rejects the agreement, you can use the following guide.

Documents: How are PDF and PDF/A document types are handled by eSignAnyWhere?

If you upload a PDF/A document to eSignAnyWhere it stays through the workflow a PDF/A valid document. If you are starting with a non-PDF/A document, the final document will be also a non-PDF/A document.

Documents: Is there a simple placeholder for signature fields in documents?

Yes, you may use our SigStrings to place signature fields in documents. You just have to type a string (the simplest version: `sig`) in the document and eSignAnyWhere is placing a signature field for you automatically. Here you get more information about our placeholders.

If you want to use more complex tags (e.g. for form fields, radio buttons, etc.) you may be interested in our advanced tags. This can be found in our Advanced User Guide and moreover a look into the PrepareSendEnvelopeSteps_v1 function. This function can be helpful for integrations. There is a How To use Advanced Tags Guide also available.

Adobe Reader says that documents are not vaild signed

This is typically caused by an outdated Adobe Reader with not update-to-date certificates. Please install a new version or perform an update of the certificates (Settings > Trust Manager > Update AATL/EUTL).