Info | ||
---|---|---|
| ||
Please note that this documentation and the links refer to the api v6. For more information please see the migration guide and the documentation related to v5. |
This tutorial shows how eSignAnyWhere can be implemented. This guide is intended to get to know the basics of a signature request workflow. After this guide you will be able to upload documents, create envelopes and send envelopes. For more information about the REST API you can also start with the Postman Tutorial.
Table of Contents | ||||
---|---|---|---|---|
|
eSignAnyWhere can be easily implemented. This tutorial shows you how to send your first envelope via REST api REST service of eSignAnyWhere. If you are using Postman for your REST calls please also have a look at the following Tutorial: Visit postman tutorial.
Please also see the developer mode for this tutorial: Visit developer Developer mode.
For this tutorial you can use your desired programming language (with REST support) or any REST tool (e. g. Postman). Moreover you will need an active eSignAnyWhere account for the authorization. (Even a trial account will work).
If you want to use SOAP for your API calls you can use SoapUI. For this tool you can find a tutorial here: Visit SoapUI Sample. For SOAP you might be also interested in the envelope XML guide which explains you more about the XML configuration.
If you are using JAVA you may be interested in our Java Library.
Some other interesting documentation links:
For this tutorial please use the following endpoint and the following api documentation link:
REST URI of eSignAnyWhereThe REST URI of eSignAnyWhere is: https://demo.esignanywhere.net/Api/v4v6.0/
here you can find the Swagger api documention: https://demo.esignanywhere.net/Api
The SOAP endpoint of eSignAnyWhere is: https://demo.esignanywhere.net/api.asmx
What the tutorial is about
The tutorial will show you the following basic use-case:
Expand | ||
---|---|---|
| ||
First we will have an easy api call to start with and then we will implement the above shown use case. Basically you simply upload a document. After the upload you will receive a documentId, which you need for creating an envelope with a JSON 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 starts automatically.
The eSignAnyWhere system will use callbacks (you can configure them in the envelope JSON configuration) to notify you if the envelope status has changed.
First we will have an easy api call to start with and then we will implement the above shown use case. Basically you simply upload a document. After the upload you will receive a documentId, which you need for creating an envelope with a JSON 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 starts automatically.
The eSignAnyWhere system will use callbacks (you can configure them in the envelope JSON configuration) to notify you if the envelope status has changed.
Your first api call
First we will try the connection with a version request. You can find the endpoints in the next table:
Hello World
Before starting with the first request please note the following:
All api calls need an authorization. You authorize with the
The API token is a user specific secret which should not be shared with other users. We recommend to create different API keys for different application integrations, to avoid configuring the same key in various integration systems. This allows, e.g. in case of sharing a key by mistake, to disable one key while keeping other integrations working with their existing configuration.
If you authorize with the apiToken just add the apiToken in the header of the api call. Please see the next sample authorization (Bearer token):
Key | Value |
---|---|
"Authorization" | "Bearer asdfngtmvv8pfmsuaxpzz85zux3e63dd9zttrwitx9mln6qka6tds83du3p3lroe" |
Please see the next sample authorization (api token):
Key | Value |
---|---|
"ApiToken" | "asdfngtmvv8pfmsuaxpzz85zux3e63dd9zttrwitx9mln6qka6tds83du3p3lroe" |
Version request
First we will try the connection with a version request. You can find the endpoints in the next table:
Method | REST Endpoint |
---|---|
REST | SOAP |
GET | |
https://demo.esignanywhere.net/Api/v4.0v6/system/version* | GetVersion_v1* |
*The version api call does not need an authorization.
The response should be like the following in REST:
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
{ "Success": true, "Version": "3.7.78.14788" } |
and in SOAP:
...
title | Alternative: SOAP implementation (deprecated) |
---|
| ||
"22.20.0.71" |
Upload document
Note |
---|
Authorization is required. |
Note |
---|
It is not allowed to upload multiple files at once (when more files are selected). |
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 following endpoint:
Method | REST Endpoint |
---|---|
POST | https://demo.esignanywhere.net/Api/v6/file/upload |
For this tutorial we just use a simple PDF document. You can download it here or use your own document.
You need the documentId for creating your first envelope. 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 with the following URI for REST: https://demo.esignanywhere.net/Api/v6.0/envelope/##envelopeId## (Replace the placeholder ##envelopeId## with your envelope id.
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
"3252931f-1234-420c-1234-0c7656d8d2ea" |
Prepare envelope (optional)
Note |
---|
Authorization is required. |
This step is only optional, but required if you do not have a configuration. A configuration is a definition of a signing task for one activity. So it contains information about signature fields on the document, form-fields, etc. With the Developer-Feature of eSignAnyWhere 2.6 it is not required anymore.
A configuration is required for each signing step in your workflow. If you have already your configuration you can skip this step.
To receive an adhoc configuration you can use the following endpoint:
Method | REST Endpoint |
---|---|
POST | https://demo.esignanywhere.net/Api/v6/file/prepare |
Code Block | ||
---|---|---|
|
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
<apiResult version="3.7.78.14788">
<baseResult>ok</baseResult>
</apiResult> |
Two ways of authorization
Almost all API calls are expecting an authorization. Therefore, your organization key and your email-address of a PowerUser is required or the apiToken. You can find the organization key in the Settings/Api Token and Apps in eSignAnyWhere. The email-address and the name of the PowerUser is used for sending the email.
You can either authorize with the organizationKey and the UserLoginName or you can use the apiToken for the authorization. For more informtaion about the two different authorizations please have a look at the Postman Tutorial
Expand | |||||||
---|---|---|---|---|---|---|---|
| |||||||
Code Block | language | xml
| |||||
<authorization>
<organizationKey>4647688a-xxxx-xxxx-xxxx-xxxxxxxx</organizationKey>
<userLoginName>your@email.address</userLoginName>
</authorization>
|
| ||||||
{
"FileIds": [
"3252931f-1234-420c-1234-0c7656d8d2ea"
]
} |
Additional parameters can be added to this call (optional):
Code Block | |||||||
---|---|---|---|---|---|---|---|
| xml
| ||||||
<authorization>
<organizationKey>4647688a-xxxx-xxxx-xxxx-xxxxxxxx</organizationKey>
<userLoginName>your@email.address</userLoginName>
</authorization> |
| ||||||
{
"FileIds": [
...
],
"ClearFieldMarkupString": true,
"SigStringConfigurations": [
{
"StartPattern": "string",
"EndPattern": "string",
"ClearSigString": true,
"SearchEntireWordOnly": true
}
]
} |
The following response shows an empty document with no unassigned elements and no assigned activities. If there are any form fields already on the document you will get the configuration shown with this call.
Code Block | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
Code Block | language | xml
| ||||||||
<authorization>
<apiToken >hizit4enf8ellb6b5hwh5b------------------------------</apiToken >
</authorization> |
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
<authorization>
<apiToken >hizit4enf8ellb6b5hwh5b------------------------------</apiToken >
</authorization> |
Errors:
For REST you get a HTTP status for the calls (for example: 200 OK or 401 unauthorized).
Expand | |||||||||
---|---|---|---|---|---|---|---|---|---|
| |||||||||
In case of errors, the error message is part of the response. In baseResult you can see the state of the call (ok/failed) and in the error-Info or ok-Info the response. The following code shows you an authorization error:
In case of errors, the error message is part of the response. In baseResult you can see the state of the call (ok/failed) and in the error-Info or ok-Info the response. The following code shows you an authorization error: |
Upload document
Note |
---|
Note: This call needs the authorization. |
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 following endpoints:
| ||
{
"UnassignedElements": {
"TextBoxes": [],
"CheckBoxes": [],
"ComboBoxes": [],
"RadioButtons": [],
"ListBoxes": [],
"Signatures": [],
"Attachments": [],
"LinkConfiguration": {
"HyperLinks": [],
"DocumentLinks": []
}
},
"Activities": []
} |
Send envelope
Note |
---|
Authorization is required. |
For sending an envelope we are using the following endpoint:
Method | REST Endpoint | |||||
---|---|---|---|---|---|---|
POST | REST | https://demo.esignanywhere.net/Api/ | v4.0v6/ | sspfileenvelope/ | uploadtemporaryUploadTemporarySspFile_v1 |
For this tutorial we just use a simple PDF document. You can download it here or use your own document.
The envelope configuration defines the envelope and the steps in the workflow. For each action you need to define a configuration, which defines what the signer has to do in his/her singing task.
You can find a sample configuration which contains two actions (one action which contains a signer with ClickToSign and one Action which contains a send copy to the given recipient configuration) for this call in the next section:
Warning | ||
---|---|---|
The recipient language must be supported by your organization (Settings->Localization) | ||
Expand | ||
| ||
You need to Base64 encode the file. |
Code Block | |||||||||
---|---|---|---|---|---|---|---|---|---|
| xml
| firstline
| 0
| ||||||
<file>
<name>eSignAnyWhere_Tutorial.pdf</name>
<data>##BASE64-FILE-CONTENT##</data>
</file> |
The response after a successfull upload of the file is the document id (SspFileId).
You need the document Id for creating your first envelope. 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 with the following URI for REST: https://demo.esignanywhere.net/Api/v4.0/envelope/##envelopeId## (Replace the placeholder ##envelopeId## with your envelope id.
Get Workstep Configuration
This step is only optional! But required if you do not 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. If you have already your workstep configuration you can skip this step. Moreover you can generate a workstep configuration with the SIGNificant Workstep Designer (Note: Only for XML). The SIGNificant Workstep Designer allows you as a developer to configure a SignAnyWhere workstep, set signature fields and types and many more. You can also use the developer mode for JSON (REST) and SOAP(XML)
To receive an adhoc workstep configuration you can use the following endpoint:
...
REST
...
SOAP
...
You can find a sample configuration for this call in the next section
Code Block | ||||
---|---|---|---|---|
| ||||
{
"SspFileIds": [
"##FileId##"
],
"AdHocWorkstepConfiguration": {
"WorkstepLabel": "string",
"SmallTextZoomFactorPercent": 0,
"WorkstepTimeToLiveInMinutes": 0,
"FinishAction": {
"ClientActions": [
{
"RemoveDocumentFromRecentDocumentList": true,
"CallClientActionOnlyAfterSuccessfulSync": true,
"ClientName": "string",
"CloseApp": true,
"Action": "string"
}
]
},
"NoSequenceEnforced": true,
"SigTemplate": {
"Size": {
"Height": 0,
"Width": 0
},
"AllowedSignatureTypes": [
]
},
"ParseFormFields": {
"MapRequiredFieldsToRequiredTask": true,
"FormsGrouping": "PerPage",
"ReturnSimplifiedConfig": true,
"AddKeepExistingValueFlag": true,
"ParseFormField": true
},
"AdhocPolicies": {
"AllowModificationsAfterSignature": true
},
"ViewerPreferences": {
"ShowPageNavigationBar": true,
"ShowThumbnails": true,
"SkipFinishConfirmDialog": true,
"SkipDocumentDialog": true,
"ShowImagesInFullWidth": true,
"DisableGeolocation": true,
"ShowDocumentDownloadDialogAfterAutomaticFinish": true,
"AttachmentsMaxFileSize": 0,
"SkipPreviewImageOnDisposableCertificate": true,
"LoadCustomJs": true,
"AllowCustomButtons": true,
"GuidingBehavior": "GuideOnlyRequiredTasks",
"FormFieldsGuidingBehavior": "AllowSubmitAlways",
"ShowVersionNumber": true,
"EnableWarningPopupOnLeave": true,
"WarningPopupDisplayAfter": "FillOrSignField",
"FinishWorkstepOnOpen": true,
"AutoFinishAfterRequiredTasksDone": true,
"GuidingBehaviorOnFinishedTask": "NoMove",
"SkipThankYouDialog": true,
"NativeAppsUrlScheme": "string",
"DocumentViewingMode": "EndlessPaperAllDocuments",
"ThumbnailMode": "ShowAllPages",
"ShowTopBar": true,
"DisplayRejectButtonInTopBar": true,
"MultipleSignatureTypesAndBatchSigningSettings": {
"IsUseBatchSigningCheckedByDefault": true,
"IsRememberSignatureTypeCheckedByDefault": true,
"IsRememberBatchSigningDecisionCheckedByDefault": true,
"SkipMultipleSignatureTypesAndBatchSigningDialogIfBatchSigningPossible": true
},
"VisibleAreaOptions": {
"AllowedDomain": "string",
"Enabled": true
},
"ShowStartGuidingHint": true,
"ShowStatusBar": true,
"ShowZoomButtons": true,
"ShowNoGeolocationWarning": true,
"AutoStartGuiding": true,
"ShowPageGap": true,
"ShowPageNavigationButtons": true,
"ShowFinishPossibleHint": true,
"SkipRejectConfirmDialog": true,
"BatchSigningType": "Basic",
"BatchSigningDisableNextButtonUntilDialogScrolledToBottom": true
},
"SignatureConfigurations": [
{
"SpcId": "string",
"PdfSignatureProperties": {
"PdfAConformant": true,
"PAdESPart4Compliant": true,
"IncludeSigningCertificateChain": true,
"SigningCertificateRevocationInformationIncludeMode": "DoNotInclude",
"SignatureTimestampData": {
"Uri": "string",
"Username": "string",
"Password": "string",
"SignatureHashAlgorithm": "Sha1",
"AuthenticationCertifiateDescriptor": {
"Identifier": "string",
"Type": "string"
}
},
"EnableEutlVerification": true,
"EnableValidateSigningCertificateName": true,
"SigningCertificateNameRegex": "string"
},
"PdfSignatureCryptographicData": {
"SignatureHashAlgorithm": "Sha1",
"SigningCertificateDescriptor": {
"Identifier": "string",
"Type": "Sha1Thumbprint",
"Csp": "Default"
}
},
"CertificateFilter": {
"KeyUsages": [
"string"
],
"ThumbPrints": [
"string"
],
"RootThumbPrints": [
"string"
]
}
}
],
"SigStringParsingConfiguration": {
"SigStringsForParsings": [
{
"StartPattern": "string",
"EndPattern": "string",
"ClearSigString": true,
"SearchEntireWordOnly": true
}
]
},
"GeneralPolicies": {
"AllowSaveDocument": true,
"AllowSaveAuditTrail": true,
"AllowRotatingPages": true,
"AllowAppendFileToWorkstep": true,
"AllowAppendTaskToWorkstep": true,
"AllowEmailDocument": true,
"AllowPrintDocument": true,
"AllowFinishWorkstep": true,
"AllowRejectWorkstep": true,
"AllowRejectWorkstepDelegation": true,
"AllowUndoLastAction": true,
"AllowColorizePdfForms": true,
"AllowAdhocPdfAttachments": true,
"AllowAdhocSignatures": true,
"AllowAdhocStampings": true,
"AllowAdhocFreeHandAnnotations": true,
"AllowAdhocTypewriterAnnotations": true,
"AllowAdhocPictureAnnotations": true,
"AllowAdhocPdfPageAppending": true,
"AllowReloadOfFinishedWorkstep": true
},
"FinalizeActions": {
},
"TransactionCodeConfigurations": [
{
"Id": "string",
"HashAlgorithmIdentifier": "Sha1",
"Texts": [
{
"Language": "string",
"Value": "string"
}
]
}
]
},
"PrepareSendEnvelopeStepsDescriptor": {
"ClearFieldMarkupString": true
}
} |
...
title | Alternative: SOAP implementation (deprecated) |
---|
Code Block | ||||
---|---|---|---|---|
| ||||
<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> |
Send envelope
For sending an envelope we are using the following endpoints:
...
REST
...
SOAP
...
This call requires the authorization, the file id(s) and the envelope configuration. 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 singing task.
You can finde a sample configuration for this call in the next section:
Code Block | ||||
---|---|---|---|---|
| ||||
{
"SspFileIds": [
"##FileId##"
],
"SendEnvelopeDescription": {
"Name": "test",
"EmailSubject": "Please sign the enclosed envelope",
"EmailBody": "Dear #RecipientFirstName# #RecipientLastName#\n\n#PersonalMessage#\n\nPlease sign the envelope #EnvelopeName#\n\nEnvelope will expire at #ExpirationDate#",
"DisplayedEmailSender": "",
"EnableReminders": true,
"FirstReminderDayAmount": 5,
"RecurrentReminderDayAmount": 3,
"BeforeExpirationDayAmount": 3,
"DaysUntilExpire": 28,
"CallbackUrl": "",
"StatusUpdateCallbackUrl": "",
"Steps": [
{
"OrderIndex": 1,
"Recipients": [
{
"Email": "##EMAIL##",
"FirstName": "##NAME##",
"LastName": "##NAME##",
"LanguageCode": "en",
"EmailBodyExtra": "",
"DisableEmail": false,
"AddAndroidAppLink": false,
"AddIosAppLink": false,
"AddWindowsAppLink": false,
"AllowDelegation": false,
"AllowAccessFinishedWorkstep": false,
"SkipExternalDataValidation": false,
"AuthenticationMethods": [
{
"Method": "Pin",
"Parameter": "1234"
}
]
}
],
"EmailBodyExtra": "",
"RecipientType": "Signer",
"WorkstepConfiguration": {
"WorkstepLabel": "test",
"SmallTextZoomFactorPercent": 100,
"FinishAction": {
"ServerActions": [],
"ClientActions": []
},
"ReceiverInformation": {
"UserInformation": {
"FirstName": "##NAME##",
"LastName": "##NAME##",
"EMail": "##EMAIL##"
},
"TransactionCodePushPluginData": []
},
"SenderInformation": {
"UserInformation": {
"FirstName": "##NAME##",
"LastName": "##NAME##",
"EMail": "##EMAIL##"
}
},
"TransactionCodeConfigurations": [
{
"Id": "smsAuthTransactionCodeId",
"HashAlgorithmIdentifier": "Sha256",
"Texts": [
]
}
],
"SignatureConfigurations": [],
"ViewerPreferences": {
"FinishWorkstepOnOpen": false,
"VisibleAreaOptions": {
"AllowedDomain": "*",
"Enabled": false
}
},
"ResourceUris": {
"SignatureImagesUri": "http://beta4.testlab.xyzmo.com//Resource/SignatureImages/?link=1agjn5MvqNpSt2jFiZQySxLEiAO~ecLOxKqy3soEHk2F4Dz1MPSYLxRkpA21XMkYY"
},
"AuditingToolsConfiguration": {
"WriteAuditTrail": false,
"NotificationConfiguration": {}
},
"Policy": {
"GeneralPolicies": {
"AllowSaveDocument": true,
"AllowSaveAuditTrail": true,
"AllowRotatingPages": false,
"AllowEmailDocument": true,
"AllowPrintDocument": true,
"AllowFinishWorkstep": true,
"AllowRejectWorkstep": true,
"AllowRejectWorkstepDelegation": false,
"AllowUndoLastAction": false,
"AllowAdhocPdfAttachments": false,
"AllowAdhocSignatures": false,
"AllowAdhocStampings": false,
"AllowAdhocFreeHandAnnotations": false,
"AllowAdhocTypewriterAnnotations": false,
"AllowAdhocPictureAnnotations": false,
"AllowAdhocPdfPageAppending": false
},
"WorkstepTasks": {
"PictureAnnotationMinResolution": 0,
"PictureAnnotationMaxResolution": 0,
"PictureAnnotationColorDepth": "Color16M",
"SequenceMode": "NoSequenceEnforced",
"PositionUnits": "PdfUnits",
"ReferenceCorner": "Lower_Left",
"Tasks": [
{
"Texts": [
{
"Language": "*",
"Value": "Signature Disclosure Text"
},
{
"Language": "en",
"Value": "Signature Disclosure Text"
}
],
"Headings": [
{
"Language": "*",
"Value": "Signature Disclosure Subject"
},
{
"Language": "en",
"Value": "Signature Disclosure Subject"
}
],
"IsRequired": false,
"Id": "ra",
"DisplayName": "ra",
"DocRefNumber": 1,
"DiscriminatorType": "Agreements"
},
{
"PositionPage": 1,
"Position": {
"PositionX": 63.0,
"PositionY": 603.0
},
"Size": {
"Height": 80.0,
"Width": 190.0
},
"AdditionalParameters": [
{
"Key": "enabled",
"Value": "1"
},
{
"Key": "positioning",
"Value": "onPage"
},
{
"Key": "req",
"Value": "1"
},
{
"Key": "fd",
"Value": ""
},
{
"Key": "fd_dateformat",
"Value": "dd-MM-yyyy HH:mm:ss"
},
{
"Key": "fd_timezone",
"Value": "datetimeutc"
},
{
"Key": "spcId",
"Value": "tLevelId"
}
],
"AllowedSignatureTypes": [
{
"AllowedCapturingMethod": "Click2Sign",
"Id": "679dd763-6e25-4a68-929d-cb1ce13dac7e",
"DiscriminatorType": "SigTypeClick2Sign",
"Preferred": false,
"StampImprintConfiguration": {
"DisplayExtraInformation": true,
"DisplayEmail": true,
"DisplayIp": true,
"DisplayName": true,
"DisplaySignatureDate": true,
"FontFamily": "Times New Roman",
"FontSize": 11.0
}
}
],
"UseTimestamp": false,
"IsRequired": true,
"Id": "1#XyzmoDuplicateIdSeperator#Signature_a1e940eb-bcd5-2222-9777-f3570faedf3f",
"DisplayName": "",
"DocRefNumber": 1,
"DiscriminatorType": "Signature"
}
]
}
},
"Navigation": {
"HyperLinks": [],
"Links": [],
"LinkTargets": []
}
},
"DocumentOptions": [
{
"DocumentReference": "1",
"IsHidden": false
}
],
"UseDefaultAgreements": true
},
{
"OrderIndex": 2,
"Recipients": [
{
"Email": "##EMAIL##",
"FirstName": "##NAME##",
"LastName": "##NAME##",
"LanguageCode": "en",
"EmailBodyExtra": "",
"DisableEmail": false,
"AddAndroidAppLink": false,
"AddIosAppLink": false,
"AddWindowsAppLink": false,
"AllowDelegation": false,
"SkipExternalDataValidation": false,
"AuthenticationMethods": []
}
],
"EmailBodyExtra": "",
"RecipientType": "Cc",
"DocumentOptions": [],
"UseDefaultAgreements": false
}
],
"AddFormFields": {
"Forms": {}
},
"OverrideFormFieldValues": {
"Forms": {}
},
"AttachSignedDocumentsToEnvelopeLog": false
}
} |
...
title | Alternative: SOAP implementation (deprecated) |
---|
Code Block | ||||
---|---|---|---|---|
| ||||
<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##&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>
<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>
</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> |
This is the simplest form of a workstep configuration. With the Developer Feature of eSAW 2.6+ you can download the envelope JSON or the envelope XML including the workstep configuration of any envelope designed in eSAW UI. The second signer only receives a copy, so he/she does not need to have a workstep configuration.
If the creation of the envelope was successful, you will get the envelope id as response.
In REST:
Code Block | ||||
---|---|---|---|---|
| ||||
{ "EnvelopeId": "56db6133-xxxx-xxxx-xxxx-xxxxxxxxxxxx" } |
...
title | Alternative: SOAP implementation (deprecated) |
---|
Code Block | ||||
---|---|---|---|---|
| ||||
<apiResult version="2.2.458.6616">
<baseResult>ok</baseResult>
<okInfo>
<envelopeId>56db6133-xxxx-xxxx-xxxx-xxxxxxxxxxxx</envelopeId>
</okInfo>
</apiResult> |
After the successful creation of the envelope, it is sent to the first recipient. The envelope id is used for managing the envelopes (send reminder, cancel delete, reject envelope,…).
Warning |
---|
The recipient language must be supported by your organization (Settings->Localization). |
Find the envelope
After sending the envelope you can use the following api call to search for the envelope:
...
REST
...
SOAP
...
In the next section you can find a sample configuration which you need for the api call:
Code Block | ||||
---|---|---|---|---|
| ||||
{
"StartDate": "2020-04-17T13:09:50.089Z",
"EndDate": "2020-04-17T13:09:50.089Z",
"SearchText": "string",
"Status": "Draft",
"InStatusSinceDays": 0,
"Senders": [
"string"
],
"Signers": [
"string"
],
"Recipients": [
"string"
],
"WaitingForRecipient": "string",
"Bulk": "string"
} |
...
title | Alternative: SOAP implementation (deprecated) |
---|
Code Block | ||||
---|---|---|---|---|
| ||||
<findEnvelopesDescriptor>
<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>
<sentBeforeDate>2017-05-10T11:18:37.2415657Z</sentBeforeDate>
<searchText/>
<hasSender>
<eMail/>
</hasSender>
<hasSigner>
<eMail/>
</hasSigner>
<hasRecipient>
<eMail/>
</hasRecipient>
<waitingForRecipient/>
</findEnvelopesDescriptor> |
You can search for the following status:
...
REST
...
SOAP
...
If you search for templates you will get the templateId which you need for the following api calls:
...
REST
...
SOAP
...
For more information about the process of finding the template and send an envelope from the template please also have a look at the template use case.
If you have not finished the envelope then search for “Active” envelopes, if the envelope is already finished please search for “Completed” envelopes to find the envelope you have sent in the api call above.
As response from this api call you will get a list of all envelopes which fulfill the status.
Envelope Status & Callback
The envelope id can be used any time to receive the envelope status. Therefore, you simply call:
...
REST
...
SOAP
...
You can find a sample response for this call in the next section:
Code Block | ||||
---|---|---|---|---|
| ||||
{ "Status": "InProgress", "SendDate": "2020-03-17T08:24:47.62Z", "ExpirationDate": "2020-04-14T08:24:47.62", "Bulks": [ { "Status": "InProgress", "Email": "", "LogDocumentId": "", "FinishedDocuments": [], "Steps": [ { "Id": "c211d550-25c5-4f61-94f9-9eb5695685fd", "FirstName": "##NAME##", "LastName": "##NAME##", "OrderIndex": 1, "Email": "##EMAIL##", "LanguageCode": "en", "Status": "NotSigned", "StatusReason": "", "RecipientType": "Signer", "OpenedDate": "2020-03-17T08:24:59.383Z", "WorkstepRedirectionUrl": "http://beta4.testlab.xyzmo.com/workstepredirector/sign?identifier=##RedirectionURL##", "AllowAccessFinishedWorkstep": false, "Authentication": [ { "Method": "Pin", "Parameter": "1234", "Filters": [] } ], "IsParallel": false, "WorkstepConfiguration": { "WorkstepLabel": "test", "SmallTextZoomFactorPercent": 100, "FinishAction": { "ServerActions": [ { "CallSynchronous": false, "Action": "http://beta4.testlab.xyzmo.com//workstepredirector/setfinishaction?wid=##WorkstepId##" } ], "ClientActions": [] }, "ReceiverInformation": { "UserInformation": { "FirstName": "##NAME##", "LastName": "##NAME##", "EMail": "##EMAIL##" }, "TransactionCodePushPluginData": [] }, "SenderInformation": { "UserInformation": { "FirstName": "##NAME##", "LastName": "##NAME##", "EMail": "##EMAIL##" } }, "TransactionCodeConfigurations": [ { "Id": "otpSignatureSmsText", "HashAlgorithmIdentifier": "Sha256", "Texts": [ ] } ], "SignatureConfigurations": [ { "PdfSignatureProperties": { "PdfAConformant": false, "PAdESPart4Compliant": false, "IncludeSigningCertificateChain": false, "SigningCertificateRevocationInformationIncludeMode": "DoNotInclude" }, "PdfSignatureCryptographicData": { "SignatureHashAlgorithm": "Sha256", "SigningCertificateDescriptor": { "Identifier": "14527A6BCFA8B4D7D0183FCA6B735B1C246D14AE", "Type": "Sha1Thumbprint", "Csp": "Default" } } }, { "SpcId": "timestampSigningId", "PdfSignatureProperties": { "PdfAConformant": false, "PAdESPart4Compliant": false, "IncludeSigningCertificateChain": false, "SigningCertificateRevocationInformationIncludeMode": "DoNotInclude", "SignatureTimestampData": { "Uri": "https://timestamp.test.namirialtsp.com", "Username": "xyzmo", "Password": "xyzmo", "SignatureHashAlgorithm": "Sha256" } }, "PdfSignatureCryptographicData": { "SignatureHashAlgorithm": "Sha256", "SigningCertificateDescriptor": { "Identifier": "14527A6BCFA8B4D7D0183FCA6B735B1C246D14AE", "Type": "Sha1Thumbprint", "Csp": "Default" } } }, { "SpcId": "padesSigningId", "PdfSignatureProperties": { "PdfAConformant": false, "PAdESPart4Compliant": true, "IncludeSigningCertificateChain": false, "SigningCertificateRevocationInformationIncludeMode": "IncludeDss" }, "PdfSignatureCryptographicData": { "SignatureHashAlgorithm": "Sha256", "SigningCertificateDescriptor": { "Identifier": "14527A6BCFA8B4D7D0183FCA6B735B1C246D14AE", "Type": "Sha1Thumbprint", "Csp": "Default" } } }, { "SpcId": "padesTimestampSigningId", "PdfSignatureProperties": { "PdfAConformant": false, "PAdESPart4Compliant": true, "IncludeSigningCertificateChain": false, "SigningCertificateRevocationInformationIncludeMode": "IncludeDss", "SignatureTimestampData": { "Uri": "https://timestamp.test.namirialtsp.com", "Username": "xyzmo", "Password": "xyzmo", "SignatureHashAlgorithm": "Sha256" } }, "PdfSignatureCryptographicData": { "SignatureHashAlgorithm": "Sha256", "SigningCertificateDescriptor": { "Identifier": "14527A6BCFA8B4D7D0183FCA6B735B1C246D14AE", "Type": "Sha1Thumbprint", "Csp": "Default" } } }, { "SpcId": "padesRemoteCertificateSigningId", "PdfSignatureProperties": { "PdfAConformant": false, "PAdESPart4Compliant": true, "IncludeSigningCertificateChain": false, "SigningCertificateRevocationInformationIncludeMode": "IncludeDss" }, "PdfSignatureCryptographicData": { "SignatureHashAlgorithm": "Sha256", "SigningCertificateDescriptor": { "Identifier": "14527A6BCFA8B4D7D0183FCA6B735B1C246D14AE", "Type": "Sha1Thumbprint", "Csp": "Default" } } }, { "SpcId": "padesRemoteCertificateTimestampSigningId", "PdfSignatureProperties": { "PdfAConformant": false, "PAdESPart4Compliant": true, "IncludeSigningCertificateChain": false, "SigningCertificateRevocationInformationIncludeMode": "IncludeDss", "SignatureTimestampData": { "Uri": "https://timestamp.test.namirialtsp.com", "Username": "xyzmo", "Password": "xyzmo", "SignatureHashAlgorithm": "Sha256" } }, "PdfSignatureCryptographicData": { "SignatureHashAlgorithm": "Sha256", "SigningCertificateDescriptor": { "Identifier": "14527A6BCFA8B4D7D0183FCA6B735B1C246D14AE", "Type": "Sha1Thumbprint", "Csp": "Default" } } }, { "SpcId": "automaticSigningId", "PdfSignatureProperties": { "PdfAConformant": false, "PAdESPart4Compliant": false, "IncludeSigningCertificateChain": false, "SigningCertificateRevocationInformationIncludeMode": "DoNotInclude" }, "PdfSignatureCryptographicData": { "SignatureHashAlgorithm": "Sha256", "SigningCertificateDescriptor": { "Identifier": "14527A6BCFA8B4D7D0183FCA6B735B1C246D14AE", "Type": "Sha1Thumbprint", "Csp": "Default" } } }, { "SpcId": "automaticTimestampSigningId", "PdfSignatureProperties": { "PdfAConformant": false, "PAdESPart4Compliant": false, "IncludeSigningCertificateChain": false, "SigningCertificateRevocationInformationIncludeMode": "DoNotInclude", "SignatureTimestampData": { "Uri": "https://timestamp.test.namirialtsp.com", "Username": "xyzmo", "Password": "xyzmo", "SignatureHashAlgorithm": "Sha256" } }, "PdfSignatureCryptographicData": { "SignatureHashAlgorithm": "Sha256", "SigningCertificateDescriptor": { "Identifier": "14527A6BCFA8B4D7D0183FCA6B735B1C246D14AE", "Type": "Sha1Thumbprint", "Csp": "Default" } } }, { "SpcId": "swissComSigningId", "PdfSignatureProperties": { "PdfAConformant": false, "PAdESPart4Compliant": true, "IncludeSigningCertificateChain": false, "SigningCertificateRevocationInformationIncludeMode": "IncludeDss" }, "PdfSignatureCryptographicData": { "SignatureHashAlgorithm": "Sha256", "SigningCertificateDescriptor": { "Identifier": "14527A6BCFA8B4D7D0183FCA6B735B1C246D14AE", "Type": "Sha1Thumbprint", "Csp": "Default" } } }, { "SpcId": "tLevelId", "PdfSignatureProperties": { "PdfAConformant": false, "PAdESPart4Compliant": true, "IncludeSigningCertificateChain": true, "SigningCertificateRevocationInformationIncludeMode": "DoNotInclude", "SignatureTimestampData": { "Uri": "https://timestamp.test.namirialtsp.com", "Username": "xyzmo", "Password": "xyzmo", "SignatureHashAlgorithm": "Sha256" } }, "PdfSignatureCryptographicData": { "SignatureHashAlgorithm": "Sha256", "SigningCertificateDescriptor": { "Identifier": "14527a6bcfa8b4d7d0183fca6b735b1c246d14ae", "Type": "Sha1Thumbprint", "Csp": "Default" } } } ], "ViewerPreferences": { "FinishWorkstepOnOpen": false, "VisibleAreaOptions": { "AllowedDomain": "*", "Enabled": false } }, "ResourceUris": { "SignatureImagesUri": "http://beta4.testlab.xyzmo.com//Resource/SignatureImages/?link=1WStxYx9aVh2bKgPnnOoA2x56aVWCf/oMP6GirOkH5eOattOs60C8lVAATUnqhUHa" }, "Policy": { "GeneralPolicies": { "AllowSaveDocument": true, "AllowSaveAuditTrail": true, "AllowRotatingPages": false, "AllowAppendFileToWorkstep": false, "AllowAppendTaskToWorkstep": false, "AllowEmailDocument": true, "AllowPrintDocument": true, "AllowFinishWorkstep": true, "AllowRejectWorkstep": true, "AllowRejectWorkstepDelegation": false, "AllowUndoLastAction": false, "AllowColorizePdfForms": false, "AllowAdhocPdfAttachments": false, "AllowAdhocSignatures": false, "AllowAdhocStampings": false, "AllowAdhocFreeHandAnnotations": false, "AllowAdhocTypewriterAnnotations": false, "AllowAdhocPictureAnnotations": false, "AllowAdhocPdfPageAppending": false }, "WorkstepTasks": { "PictureAnnotationMinResolution": 0, "PictureAnnotationMaxResolution": 0, "PictureAnnotationColorDepth": "Color16M", "SequenceMode": "NoSequenceEnforced", "PositionUnits": "PdfUnits", "ReferenceCorner": "Lower_Left", "Tasks": [ { "Texts": [ { "Language": "*", "Value": "Signature Disclosure Text" }, { "Language": "en", "Value": "Signature Disclosure Text" } ], "Headings": [ { "Language": "*", "Value": "Signature Disclosure Subject" }, { "Language": "en", "Value": "Signature Disclosure Subject" } ], "IsRequired": false, "Id": "ra", "DisplayName": "ra", "DocRefNumber": 1, "DiscriminatorType": "Agreements" }, { "PositionPage": 1, "Position": { "PositionX": 63.0, "PositionY": 603.0 }, "Size": { "Height": 80.0, "Width": 190.0 }, "AdditionalParameters": [ { "Key": "enabled", "Value": "1" }, { "Key": "positioning", "Value": "onPage" }, { "Key": "req", "Value": "1" }, { "Key": "fd", "Value": "" }, { "Key": "fd_dateformat", "Value": "dd-MM-yyyy HH:mm:ss" }, { "Key": "fd_timezone", "Value": "datetimeutc" }, { "Key": "spcId", "Value": "tLevelId" } ], "AllowedSignatureTypes": [ { "AllowedCapturingMethod": "Click2Sign", { "Documents": [{ "FileId": "d33d43ca-1234-1234-1234-b645fc4e0fb2", "DocumentNumber": 1 } ], "Name": "Test", "Activities": [{ "Action": { "Sign": { "RecipientConfiguration": { "ContactInformation": { "Email": "jane.doe@sample.com", "GivenName": "Jane", "Surname": "Doe", "Id"LanguageCode": "679dd763-6e25-4a68-929d-cb1ce13dac7e",EN" } "DiscriminatorType": "SigTypeClick2Sign"}, "Elements": { "PreferredSignatures": false,[{ "ElementId": "sample sig click2sign", "StampImprintConfiguration": { "Required": true, "DisplayExtraInformationDocumentNumber": true1, "DisplayName": "Sign here", "DisplayEmail": true, "AllowedSignatureTypes": { "DisplayIpClickToSign": true, { } "DisplayName": true, }, "FieldDefinition": { "DisplaySignatureDate": true, "Position": { "FontFamily": "Times New Roman", "PageNumber": 1, "FontSizeX": 11.0100, "Y": 200 } }, } "Size": { ], "Width": 100, "UseTimestamp": false, "Height": 70 "IsRequired": true, } "Id": "1#XyzmoDuplicateIdSeperator#Signature_a1e940eb-bcd5-2222-9777-f3570faedf3f", } } "DisplayName": "", ] } "DocRefNumber": 1, } } }, { "DiscriminatorTypeAction": "Signature"{ "SendCopy": { } "RecipientConfiguration": { "ContactInformation": { ] "Email": "john.doe@sample.com", } }"GivenName": "John", "NavigationSurname": {"Doe", "HyperLinksLanguageCode": [],"EN" } "Links": [], } "LinkTargets": [] } } } ] } |
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
{ }"EnvelopeId": "45fd01ce-1234-4792-1234-f5230e41b130" } |
The envelope id is used for managing the envelopes (send reminder, cancel delete, reject envelope,…).
After the successful creation of the envelope, it is sent to the first recipient.
Open the envelope
After you have sent the envelope and you have got the envelopeId you can call the method https://demo.esignanywhere.net/api/v6/envelope/{envelopeId}/viewerlinks. With the result of this method you get information about the envelope and you can find the workstepRedirectionURL (Viewerlink).
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
{ },"ViewerLinks": [ { "IdActivityId": "ff4b740e5609d2ea-f0a81234-4e691234-ad321234-54cae61049931959e63fde64", "FirstName"Email": "##NAME##john.doe@sample.com", "LastNameViewerLink": "##NAME##", "OrderIndex": 2, https://demo.esignanywhere.net/workstepredirector/sign?identifier=mdIkzVC1234512IgiOLD3Iodfynd~12345RbJQXusyZuCNp7FR6PniOT12345B~fQ1234A==" } ] } |
With this redirection link it is possible to open and sign the document in your web portal.
Find the envelope
Note |
---|
Authorization is required. |
After sending the envelope you can use the following api call to search for the envelope:
Method | REST Endpoint |
---|---|
POST | https://demo.esignanywhere.net/Api/v6/envelope/find |
In the next section you can find a sample configuration which you need for the api call:
Following status are available:
- Canceled
- Completed
- Expired
- Rejected
- ActionRequired
- WaitingForOthers
- ExpiringSoon
- Active
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
{
"StartDate": "2022-12-05T13:09:53.052Z",
"EndDate": "2022-12-05T13:09:53.052Z",
"SearchText": "HelloWorld",
"Status": "Canceled",
"InStatusSinceDays": 10,
"SenderEmail": "john.doe@sample.com",
"SignerEmail": "jane.doe@sample.com",
"RecipientEmail": "jane.doe@sample.com",
"WaitingForRecipientWithEmail": "jane.doe@sample.com",
"BulkParentId": "83467fdc-1234-4592-1234-9c64787cd7a1"
} |
Please note: The SearchText searches texts within the following elements:
- Recipient
- First name
- Last name
- Email address
- Email body
- Envelope
- Subject
- Email body
- Envelope name
- Envelope description
- Sender
- First name
- Last name
- Email address
- User id
Please note that the configuration above shows all available filters you may want to use. You can also just search for example for completed envelopes. Therefore only the following configuration is needed:
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
{
"Status": "Completed",
} |
You can search for the following status:
Status |
---|
Canceled |
Completed |
Expired |
Rejected |
ActionRequired |
WaitingForOthers |
ExpiringSoon |
Active |
If you have not finished the envelope then search for “Active” envelopes, if the envelope is already finished please search for “Completed” envelopes to find the envelope you have sent in the api call above.
As response from this api call you will get a list of all envelopes which fulfill the status. Please see the following sample response:
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
{ "Envelopes": [ "Email": "##EMAIL##", "LanguageCode": "en", "Status": "NotSigned", "StatusReason": "", "RecipientType": "Cc", "WorkstepRedirectionUrl": "", "AllowAccessFinishedWorkstep": false, "IsParallel": false, "WorkstepConfiguration": { "SmallTextZoomFactorPercent": 100, "ViewerPreferences": {}, "Policy": { "GeneralPolicies": { { "AllowRotatingPages"Status": true"Completed", "Id": "62664b59-1234-455c-1234-3ed972fe5857", "AllowFinishWorkstep"Name": true"Test2", "BulkParentId": "", "AllowUndoLastActionIsExpiringSoon": true false }, "WorkstepTasks": { "Status": "Completed", "PictureAnnotationMinResolutionId": 0"45fd01ce-1234-4792-1234-f5230e41b130", "Name": "Test", "BulkParentId": "", "PictureAnnotationMaxResolution": 0, "IsExpiringSoon": false } ] } |
Envelope information
Note |
---|
Authorization is required. |
The envelope id can be used any time to receive the envelope status. Therefore, you simply call:
Method | REST Endpoint |
---|---|
GET | https://demo.esignanywhere.net/Api/v6/envelope/##envelopeId## |
You can find a sample response for this call in the next section:
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
{ "PictureAnnotationColorDepth"Id": "Color16M45fd01ce-1234-4792-1234-f5230e41b130", "SequenceMode"EnvelopeStatus": "NoSequenceEnforcedCompleted", "PositionUnits"Name": "PdfUnitsTest", "Activities": [ { "ReferenceCornerId": "Lower_Left", e99769a9-1234-4e8a-1234-b237d41bf720", "TasksStatus": []"Completed", "FinishedDate": "2022-05-06T09:00:33.37+00:00", }"OpenedDate": "2022-05-06T09:00:16.553+00:00", "Action": { } "Sign": { } "ContactInformation": { } ] } ], "Email": "##EMAIL##", "Documents": [ { "PageSizesInPointsGivenName": ["##NAME##", { "Height"Surname": 792.0"##NAME##", "WidthLanguageCode": 612.0"EN" } } ], "DocRefNumber": 1,} "FileName": "test.pdf",} }, "FormFields": [] { } ], "Id": "62ce2b28be0c0dd0-deb91234-40a04d6b-96561234-88609353494b7771138f19e8", "Bulk": "", "BasicOptions": { "NameStatus": "testCompleted", "EmailSubjectFinishedDate": "Please sign the enclosed envelope", "2022-05-06T09:00:39.277+00:00", "EmailBody": "Dear #RecipientFirstName# #RecipientLastName#\n\n#PersonalMessage#\n\nPlease sign the envelope #EnvelopeName#\n\nEnvelope will expire at #ExpirationDate#", Action": { "EnableRemindersSendCopy": true,{ "FirstReminderDayAmount": 5, "RecurrentReminderDayAmountContactInformation": 3, { "BeforeExpirationDayAmount": 3 } } | ||||||
Expand | ||||||
| ||||||
Code Block | | |||||
|
Callback
The configured callback URL is 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.
Please note the following referring callbacks:
Note |
---|
Only the envelope callback 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. Therefore, please send back the HTTP 200 immediately! Due to these notes please send the message immediately after you receive the callback and before other callback-processing starts (e.g. download documents) to avoid a timeout of the callback! |
Download a finished document
To download a finished document you simply call the function:
...
REST
...
SOAP
...
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!)
You can receive the document id from the response of the getEnvelope call.
Download respoonse in REST would be for example a 200 OK status.
...
title | Alternative: SOAP implementation (deprecated) |
---|
...
language | xml |
---|---|
theme | Eclipse |
...
"Email": "##EMAIL##",
"GivenName": "##NAME##",
"Surname": "##NAME##",
"LanguageCode": "EN"
}
}
}
}
]
} |
Callback
The configured callback URL is 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 regularly.
Please note the following referring callbacks:
Note |
---|
Only the envelope callback 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. Therefore, please send back the HTTP 200 immediately! Due to these notes please send the message immediately after you receive the callback and before other callback-processing starts (e.g. download documents) to avoid a timeout of the callback! |
Download finished document
Note |
---|
Authorization is required. |
First you need the following api call to get the fileIds of the document (please note that this method is only for completed envelopes):
Method | REST Endpoint |
---|---|
GET | https://demo.esignanywhere.net/Api/v6/envelope/##envelopeId##/files |
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
{
"SentDocuments": [
{
"FileName": "test.pdf",
"PageSizes": [
{
"Width": 612.0,
"Height": 792.0
}
]
}
],
"FinishedDocuments": [
{
"FileId": "806b89db-1234-1234-908b-4f2ba4ebd19e",
"FileName": "test.pdf",
"Attachments": []
}
],
"AuditTrail": {
"FileId": "5e7b8aba-1234-1234-91f8-2c718bf913b1",
"XmlFileId": "a10a1438-1234-1234-9799-16ae3ce54c37"
},
"Disclaimers": []
} |
To download a finished document you can call the function:
Method | REST Endpoint |
---|---|
GET | https://demo.esignanywhere.net/Api/v6/file/##fileId## |
Just insert one of the following file ids:
- Finished document
- File id
- Audit trail
- Filed id
- XML File id
Info | ||
---|---|---|
| ||
Depending on the signature method used, it might be necessary or recommended to store additional documents beside the signed document, to ensure having the necessary evidence. For advanced electronic signatures, you might have to store also the audit trail document; and for Namirial Disposable Certificate, also the Certificate Request Form by which the signer requested issuance of the QEC. Those documents can be downloaded using the same method, just with the different file IDs. |
Helpful Features and Resources
...
. |