Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

SendReminders_v1: Send reminders to all recipients that currently can sign the envelope
CancelEnvelope_v1: Cancels the envelope
DeleteEnvelope_v1: Delets an envelope or a draft of an envelope
RestartEnvelope_v1: Restarts an expired envelope

Reference eSAW API

Section


Expand
titleCancelEnvelope_v1

The “cancel” operation is related to the workflow. Cancel means, an already sent signing process will be stopped and canceled. The envelope is not deleted (the same applies for a draft, as it hasn’t been started yet).


Expand
titleCopyDocumentFromTemplate_v1

For this call you just need the templateId. The response of this call is a new SspFileId and the workstep configuration of the template. Therefore, with this call you get all information (workstep configuration and the document) to send an envelope afterwards.


Expand
titleCreateDraftFromTemplate_v1

Creates a draft with the given parameters.

Parameters

sspFileIds: Reference to files already uploaded to the SSP server e.g. using the uploadTemporarySspFileV1 call

envelopeDescriptionXml: The envelope configuration (<envelope>…</envelope>). In a draft, defining a workstep configuration is not supported.

draftOptionsXml: With the draft options, the redirect url and the callback url can be specified. See also callbacks.

Code Block
languagexml
themeEclipse
<draftOptions>
    <afterSendRedirectUrl>http://www.mycallback.at/DraftAfterSendRedirect?envelope=##EnvelopeId##&action=##Action##</afterSendRedirectUrl>
    <afterSendCallbackUrl>http://www.mycallback.at/DraftAfterSendCallback?envelope=##EnvelopeId##&action=##Action##</afterSendCallbackUrl>
    <redirectPolicy>ToDesigner</redirectPolicy>
</draftOptions>

Result

DraftId


Expand
titleCreateDraft_v1

Creates the Draft on the server. See Implementation for information how to integrate the draft in your environment. For more details of parameter envelopeDescriptionXml see: The Envelope XML


Expand
titleDeleteEnvelope_v1

After an envelope has been completed (i.e. all signers signed, and the result was downloaded and stored in any kind of document management system), implementors should take care about deleting the envelope from the SignAnyWhere servers. This should be done as general system cleanup best-practise, and also for security issues (there were links sent to recipients containing the envelope reference, why do you want to keep this links alive when documents were moved to a document management system where you probably have a different permission strategy)


Expand
titleDisposeSspFile_v1

Removes the previously uploaded document (using UploadTemporarySspFile_v1) to the SIGNificant Server Platform again.


Expand
titleDownloadCompletedDocument_v1

The file id has to be retrieved from GetEnvelopeById_v1. Attention: just documents of finished envelopes can be downloaded. The returned file id from the uploading call will cause an error (invalid file id).


Expand
titleFindEnvelopes_v1

Please use the FindEnvelopes_v2 function.


Expand
titleFindEnvelopes_v2 (authorizationXML, findEnvelopesDescriptorXML, resultFormat)


Code Block
languagexml
themeEclipse
<findEnvelopesDescriptor>
  <!-- all search parameters are optional -->
  <status>Draft|Started|InProgress|Canceled|Completed|Expired|Rejected|Template|ActionRequired| WaitingForOthers|ExpiringSoon|Active</status> <inStatusSinceDays>30</inStatusSinceDays>
  <sentAfterDate>2017-02-08T12:18:37.2415657Z</sentAfterDate>
  <!-- all dates can also be "date only" -->
  <sentBeforeDate>2017-05-10T11:18:37.2415657Z</sentBeforeDate>
  <!-- search text searches for email subject, email body, envelope name, envelope description, sender user or envelope recipient; use with care because of high system impact -->
  <searchText>some text</searchText>
  <hasSender>
    <eMail>Marius.Gheorghe@eflowauto.test</eMail>
  </hasSender>
  <hasSigner>
    <eMail>Marius.Wenny@eflowauto.test</eMail>
  </hasSigner>
  <hasRecipient>
    <eMail>Fabian.Wenny@eflowauto.test</eMail>
    <!-- if just one recipient is searched for, you can leave the "eMail" tag because of backwards compatibility -->
  </hasRecipient>
  <waitingForRecipient>Fabian.Jordan@eflowauto.test</waitingForRecipient>
</findEnvelopesDescriptor>

resultFormat:
empty, “OnlyIdentifiers”, “Extended”

Important note: searchText should be used with care, because it will cause a high load on the system (string based search).


Expand
titleGetAdHocWorkstepConfiguration_v1

Sends you back an adhoc workstep configuration for a given document.

Usage


Expand
titleCall Request


Code Block
languagexml
themeEclipse
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:esig="http://www.eSignAnyWhere.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <esig:GetAdHocWorkstepConfiguration_v1>
         <!--Optional:-->
         <esig:authorizationXml>
          <authorization>
          <organizationKey>##ORGANIZATION-KEY##</organizationKey>
          <userLoginName>##USER-LOGON##;/userLoginName>
         </authorization>
         </esig:authorizationXml>
         <!--Optional:-->
         <esig:sspFileIds>
            <!--Zero or more repetitions:-->
            <esig:string>##FILE-ID##</esig:string>
         </esig:sspFileIds>
         <!--Optional:-->
         <esig:adHocWorkstepConfiguration>
         <AdhocWorkstepConfiguration>
    <!-- not relevant-->
    <WorkstepLabel>workstepLabel</WorkstepLabel>
    <!-- not relevant-->
    <SmallTextZoomFactorPercent>100</SmallTextZoomFactorPercent>
    <!-- not relevant-->
    <WorkstepTimeToLiveInMinutes>0</WorkstepTimeToLiveInMinutes>
    <!--Configure the actions done by the server and the by the clients when the workstep is finished.-->
    <FinishAction>
        <!-- not relevant-->
        <ServerAction callSynchronous="0"></ServerAction>
        <!--A client action specifies the redirect, when a recipient clicks on finish.-->    
        <ClientAction clientName="SIGNificant SignAnywhere" closeApp="0" RemoveDocumentFromRecentDocumentList="0" CallClientActionOnlyAfterSuccessfulSync="1">https://www.significant.com</ClientAction>
    </FinishAction>

    <!--Configure the adhoc workstep creation-->
    <NoSequenceEnforced>0</NoSequenceEnforced>

    <!-- Define default properties of signature fields / tasks-->
    <SigTemplate>
        <!--The elements width in points-->
        <width>50.5</width>
        <!--The elements height in points-->
        <height>100.5</height>
        <!--Parameter defining the signature type. Possible values: 'BiometricSignature', 'LocalCertificate', 'Picture', 'TransactionCode', 'TransactionCodeAndBiometricSignature', 'TransactionCodeAndLocalCertificate', 'TransactionCodeBiometricSignatureAndLocalCertificate' and 'BiometricSignature_and_LocalCertificate'. -->
        <param name="sigType">Picture</param>
        <!--Parameter that refines sigType "Picture": a list, seperated by "," from these values: Draw2Sign,Type2Sign,Click2Sign -->
        <param name="allowedCapturingMethods">Draw2Sign,Type2Sign</param>

    </SigTemplate>
    <!--Configuration for parsing the form fields. Possible values: '1' parse the form fields, '0' do not parse form fields-->
    <!--Attribute 'mapRequiredFieldsToRequiredTask': set the form filling task required when some of the fields are required. Possible values: '1' required forms lead to required tasks, '0' required fields do not enforce the task to be required-->
    <!--Attribute 'formsGrouping': Specify how the parsed forms should be grouped into tasks. Possible values: 'PerPage' all forms on one page are grouped to one forms group, 'PerDocument' all forms of one document are grouped to one forms group, 'PerEnvelope' all forms of all documents inside the envelope are grouped to one forms group-->
    <ParseFormFields mapRequiredFieldsToRequiredTask="0" formsGrouping="PerDocument">1</ParseFormFields>
    <!--If the workstep is not generated by hand but automatically generated by the Workstep Controller AdhocPolicies are specified-->
    <AdhocPolicies>
        <!-- not relevant-->
        <AllowModificationsAfterSignature>1</AllowModificationsAfterSignature>
    </AdhocPolicies>
    <!--Configurate the signatures for this workstep. One default configuration has to be defined. The default configuration is used for flatten signatures, adhoc signatures and signature fields which do not reference a special signature plugin configuration. The default configuration does not contain the attribute 'spcId'. If the attribute 'spcId' is defined the signature plugin configuration does only apply to signature fields referencing the configuration by specifiying <param name="spcId">id</param>.-->
    <signaturePluginConfiguration>
        <!--Configurate the signature properties-->
        <PdfSignatureProperties_V1>
            <!--Should the signatures be pdfA conformant. Note this setting does not convert a document into pdfA, it only keeps it pdfA conformant if it already is. Possible values: '1' sign pdfA conformant - in this case the file size will be bigger than without pdfA, '0' do not sign pdfA conformant.-->
            <PdfAConformant>0</PdfAConformant>
            <!--Defines if the signature should be PAdES part 4 compliant. Possible values: '1' sign the document PAdES part 4 compliant, '0' sign the document with standard pdf signature. Default value: '0'-->
            <PAdESPart4Compliant>1</PAdESPart4Compliant>
            <!--Defines if the certificate chain for the signing certificate should be embedded into the signature. Possible values: '1' include the certificate chain, '0' do not include the certificate chain. Default value: '0'-->
            <IncludeSigningCertificateChain>1</IncludeSigningCertificateChain>
            <!--Defines if and how the revocation information for the signing certificate chain should be embedded. Possible values: 'DoNotInclude' no revocation information is included, 'Include' the revocation information has to be included, if not possible the signature throws an exception, 'TryToInclude' if the revocation information can be fetched, it should be included, if not the signature is done without revocation information. Information about the signatures where the revocation information could not be included is saved into the WorkstepStatus, 'CheckRevocationIncludeOcsp' the revocation information has to be included when it is an OCSP, if checking of the revocation (OCSP or CRL) fails an exception is thrown. Information about the signatures where the revocation information could not be included is saved into the WorkstepStatus-->
            <SigningCertificateRevocationInformationIncludeMode>Include</SigningCertificateRevocationInformationIncludeMode>
        </PdfSignatureProperties_V1>
        <!--Configurate the cryptographic data-->
        <PdfSignatureCryptographicData_V1>
            <!--The hash algorithm used for the signatures. Possible values: 'Sha1', 'Sha256', 'Sha512'-->
            <SignatureHashAlgorithm>Sha256</SignatureHashAlgorithm>
            <!--The description of the signing certificate. More than one SigningCertificateDescriptor can be defined by adding this node more than once. If more SigningCertificateDescriptors are present, these configurations are used as backup if the selected SigningCertificateDescriptor is not working. For example if no revocation information can be retrieved although it should be included into the signature.-->
            <SigningCertificateDescriptor>
                <!--The certificates identifier-->
                <Identifier>3b777446a35fca027cbed5f69e24995945a611cb</Identifier>
                <!--The certificate identifier type. Possible values: 'Subject', 'Sha1Thumbprint'-->
                <Type>Sha1Thumbprint</Type>
                <!--The cryptographic service provider to locate the certificate. Possible values: 'default' uses the servers certificate store, 'custom' uses the custom signature action-->
                <Csp>Default</Csp>
            </SigningCertificateDescriptor>
        </PdfSignatureCryptographicData_V1>
    </signaturePluginConfiguration>

    <!--Configure the signature string parsing pattern: Text in the document will be parsed for this pattern and if found, a signature task is generated. -->
    <SigStringParsingConfiguration>
        <!--Defines a signature string to parse. Tag can be present more than once-->
        <SigStringsForParsing>
            <!--The start pattern of the signature string if it has a start and end pattern. Otherwise the whole word to parse-->
            <StartPattern>`sig</StartPattern>
            <!--End pattern if needed, otherwise empty-->
            <EndPattern>`</EndPattern>
            <!--Define if the signature strings should be cleared from the document. Possible values: '1' remove the signature strings from the document, '0' do not change the document-->
            <ClearSigString>1</ClearSigString>
            <!--Define if only the entire word should be searched. For example if start pattern is 'signature' only 'signature' but not 'signaturepad' is found. This option does only effect signature string without end patterns. Possible values: '1' search only the entire word, '0' search words containing the pattern as well.-->
            <SearchEntireWordOnly>1</SearchEntireWordOnly>
        </SigStringsForParsing>
    </SigStringParsingConfiguration>
    <!--Defines general policies for this workstep-->
    <GeneralPolicies>
        <!--Is the client allowed to save the workstep document-->
        <AllowSaveDocument>1</AllowSaveDocument>
        <!--Is the client allowed to save the audittrail document-->
        <AllowSaveAuditTrail>1</AllowSaveAuditTrail>

        <!-- not relevant-->
        <AllowFinishWorkstep>1</AllowFinishWorkstep>
        <!--Is the client allowed to reject the workstep-->
        <AllowRejectWorkstep>1</AllowRejectWorkstep>    

        <AllowAdhocPdfAttachments>1</AllowAdhocPdfAttachments>        
    </GeneralPolicies>

    <ViewerPreferences>
        <ShowVersionNumber>1</ShowVersionNumber>
        <EnableThumbnailDisplay>1</EnableThumbnailDisplay>
        <EnableWarningPopupOnLeave>1</EnableWarningPopupOnLeave>
        <WarningPopupDisplayAfter>Always</WarningPopupDisplayAfter>
        <GuidingBehavior>GuideRequiredAndOptionalTasks</GuidingBehavior>

    </ViewerPreferences>

</AdhocWorkstepConfiguration>    
         </esig:adHocWorkstepConfiguration>
      </esig:GetAdHocWorkstepConfiguration_v1>
   </soapenv:Body>
</soapenv:Envelope>



Expand
titleCall Response


Code Block
languagexml
themeEclipse
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
   <soap:Body>
      <GetAdHocWorkstepConfiguration_v1Response xmlns="http://www.eSignAnyWhere.com/">
         <GetAdHocWorkstepConfiguration_v1Result><![CDATA[<apiResult version="2.1.260.5831">
  <baseResult>ok</baseResult>
  <okInfo>
    <workstepConfiguration>
      <WorkstepLabel>workstepLabel</WorkstepLabel>
      <SmallTextZoomFactorPercent>100</SmallTextZoomFactorPercent>
      <WorkstepTimeToLiveInMinutes>0</WorkstepTimeToLiveInMinutes>
      <FinishAction>
        <ServerAction callSynchronous="0" />
        <ClientAction clientName="SIGNificant SignAnywhere" closeApp="0" RemoveDocumentFromRecentDocumentList="0" CallClientActionOnlyAfterSuccessfulSync="1">https://www.significant.com</ClientAction>
      </FinishAction>
      <signatureTemplate>
        <version>1.2.0.2</version>
        <positionUnits>PdfUnits</positionUnits>
        <positionReferenceCorner>Lower_Left</positionReferenceCorner>
      </signatureTemplate>
      <pdfForms isEditingAllowed="1" />
      <ViewerPreferences>
        <ShowVersionNumber>1</ShowVersionNumber>
        <EnableThumbnailDisplay>1</EnableThumbnailDisplay>
        <EnableWarningPopupOnLeave>1</EnableWarningPopupOnLeave>
        <WarningPopupDisplayAfter>Always</WarningPopupDisplayAfter>
        <GuidingBehavior>GuideRequiredAndOptionalTasks</GuidingBehavior>
        <FormFieldsGuidingBehavior>AllowSubmitAlways</FormFieldsGuidingBehavior>
        <FinishWorkstepOnOpen>0</FinishWorkstepOnOpen>
      </ViewerPreferences>
      <Policy version="1.0.0.2">
        <GeneralPolicies>
          <AllowSaveDocument>1</AllowSaveDocument>
          <AllowSaveAuditTrail>1</AllowSaveAuditTrail>
          <AllowRotatingPages>1</AllowRotatingPages>
          <AllowAppendFileToWorkstep>0</AllowAppendFileToWorkstep>
          <AllowAppendTasksToWorkstep>0</AllowAppendTasksToWorkstep>
          <AllowEmailDocument>0</AllowEmailDocument>
          <AllowPrintDocument>0</AllowPrintDocument>
          <AllowFinishWorkstep>1</AllowFinishWorkstep>
          <AllowRejectWorkstep>1</AllowRejectWorkstep>
          <AllowUndoLastAction>0</AllowUndoLastAction>
          <AllowColorizePdfForms>0</AllowColorizePdfForms>
          <AllowAdhocPdfAttachments>1</AllowAdhocPdfAttachments>
          <AllowAdhocSignatures>0</AllowAdhocSignatures>
          <AllowAdhocStampings>0</AllowAdhocStampings>
          <AllowAdhocFreeHandAnnotations>0</AllowAdhocFreeHandAnnotations>
          <AllowAdhocTypewriterAnnotations>0</AllowAdhocTypewriterAnnotations>
          <AllowAdhocPictureAnnotations>0</AllowAdhocPictureAnnotations>
          <AllowAdhocPdfPageAppending>0</AllowAdhocPdfPageAppending>
        </GeneralPolicies>
        <WorkstepTasks SequenceMode="SequenceOnlyRequiredTasks" originalSequenceMode="SequenceOnlyRequiredTasks" />
        <AdhocPolicies>
          <AllowModificationsAfterSignature>1</AllowModificationsAfterSignature>
        </AdhocPolicies>
      </Policy>
      <timeCreated>2017-01-17T09:55:13.2332816Z</timeCreated>
      <signaturePluginConfiguration>
        <PdfSignatureProperties_V1>
          <PdfAConformant>0</PdfAConformant>
          <PAdESPart4Compliant>1</PAdESPart4Compliant>
          <IncludeSigningCertificateChain>1</IncludeSigningCertificateChain>
          <SigningCertificateRevocationInformationIncludeMode>Include</SigningCertificateRevocationInformationIncludeMode>
        </PdfSignatureProperties_V1>
        <PdfSignatureCryptographicData_V1>
          <SignatureHashAlgorithm>Sha256</SignatureHashAlgorithm>
          <SigningCertificateDescriptor>
            <Identifier>##SIGNATURE-HASH##</Identifier>
            <Type>Sha1Thumbprint</Type>
            <Csp>Default</Csp>
          </SigningCertificateDescriptor>
        </PdfSignatureCryptographicData_V1>
      </signaturePluginConfiguration>
      <TransactionCodeConfigurations>
        <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="de">
          <Message>Bitte authentifizieren Sie sich für den Zugriff auf die Dokumentenmappe der Transaktion {tId}. Ihre TAN lautet: {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>
      </TransactionCodeConfigurations>
    </workstepConfiguration>
  </okInfo>
</apiResult>]]></GetAdHocWorkstepConfiguration_v1Result>
      </GetAdHocWorkstepConfiguration_v1Response>
   </soap:Body>
</soap:Envelope>




Expand
titleGetEnvelopeById_v1

Get the status of an envelope by its envelopeId.

The status of an envelope can be:

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

The status of an recipient can be

  • NotSigned
  • Signed
  • Rejected
  • Delegated

Usage

Expand
titleCall Result


Code Block
languagexml
themeEclipse
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
   <soap:Body>
      <GetEnvelopeById_v1Response xmlns="http://www.eSignAnyWhere.com/">
         <GetEnvelopeById_v1Result><![CDATA[<apiResult version="2.2.452.6541">
  <baseResult>ok</baseResult>
  <okInfo>
    <envelopeStatus>
      <id>62fe2dcd-811d-4ac2-9602-f146e18075c1</id>
      <name>API-Test draft to envelope</name>
      <status>Expired</status>
      <sendDate>2017-01-19T08:14:24.223Z</sendDate>
      <expirationDate>2017-01-21T08:14:24.223Z</expirationDate>
      <bulkRecipients>
        <bulkRecipient eMail="">
          <status>Expired</status>
          <recipients>
            <recipient>
              <orderIndex>1</orderIndex>
              <eMail>recipient1@email.com</eMail>
              <status>NotSigned</status>
              <signedDate></signedDate>
              <recipientType>Signer</recipientType>
              <workstepRedirectionUrl></workstepRedirectionUrl>
            </recipient>
            <recipient>
              <orderIndex>2</orderIndex>
              <eMail>recipient2@email.com</eMail>
              <status>NotSigned</status>
              <signedDate></signedDate>
              <recipientType>Signer</recipientType>
              <workstepRedirectionUrl></workstepRedirectionUrl>
            </recipient>
            <recipient>
              <orderIndex>3</orderIndex>
              <eMail>copyReceiver@somewhere.com</eMail>
              <status>NotSigned</status>
              <signedDate></signedDate>
              <recipientType>Cc</recipientType>
              <workstepRedirectionUrl></workstepRedirectionUrl>
            </recipient>
          </recipients>
          <completedDocuments>
            <logDocumentId></logDocumentId>
          </completedDocuments>
        </bulkRecipient>
      </bulkRecipients>
    </envelopeStatus>
  </okInfo>
</apiResult>]]></GetEnvelopeById_v1Result>
      </GetEnvelopeById_v1Response>
   </soap:Body>
</soap:Envelope>




Expand
titleGetLicenseState_v1

This request will return you the current status of your organization’s license. Please note that for on premise the data model is a bit different.

Code Block
languagexml
themeEclipse
<licenseInformation>
 <type>Per Number of Documents</type>
 <expirationDateUtc>2019-05-30T00:00:00</expirationDateUtc>
 <documents>
	<total>99999</total>
	<used>13</used>
 </documents>
 <users>
	<total>999999</total>
	<used>12</used>
 </users>
</licenseInformation>