The Migration Guide helps you if you want to switch from SOAP to REST API. In addition to all the differences between the individual calls, this guide also contains detailed information corresponding on the significant differences (structure, syntax and semantic) between SOAP and REST that will help you with your integration transition.
First the endpoints are different
Two SOAP endpoints: https://demo.esignanywhere.net/api.asmx?WSDL
https://demo.esignanywhere.net/UserManagementApi.asmx?WSDL
One REST endpoint (base URI):
You can find the latest version here: https://demo.esignanywhere.net/Api
The names of the api calls are different:
Authorization
| SOAP | REST |
|---|---|
| ValidateAuthorization_v1*** | authorization |
Envelope
| SOAP | REST |
|---|---|
| CreateDraft_v1* | envelope/create |
| CreateDraftFromTemplate_v1* | envelope/createFromTemplate |
| CancelEnvelope_v1* | envelope/{envelopeId}/cancel |
| GetEnvelopeById_v1* | envelope/{envelopeId} (get) |
| DeleteEnvelope_v1* | envelope/{envelopeId} (delete) |
| FindEnvelopes_v1* or FindEnvelopes_v2* | envelope/find |
| DownloadCompletedDocument_v1* | envelope/downloadCompletedDocument/{documentId} |
| DownloadEnvelopePageImage_v1* | envelope/{envelopeId}/downloadPageImage/{docRefNumber}/{pageNumber} |
| PrepareSendEnvelopeSteps_v1* | envelope/prepare |
| RestartEnvelope_v1* | envelope/{envelopeId}/restart/{expirationInDays} |
| SendEnvelope_v1* | envelope/send |
| SendEnvelopeFromTemplate_v1* | envelope/sendFromTemplate |
| SendReminders_v1* | envelope/{envelopeId}/remind |
| CopyDocumentFromTemplate_v1* | envelope/{templateId}/copyFromTemplate |
| UnlockEnvelope_v1* | envelope/{envelopeId}/unlock |
License
| SOAP | REST |
|---|---|
| GetLicenseState_v1* | license |
Recipient
| SOAP | REST |
|---|---|
| ReplaceRecipient_v1* | recipient/{recipientId}/fromEnvelope/{envelopeId} (put) |
| DeleteRecipient_v1* | recipient/{recipientId}/fromEnvelope/{envelopeId} (delete) |
SspFile
| SOAP | REST |
|---|---|
| DisposeSspFile_v1* | sspfile/disposefile/{sspFileId} |
| UploadTemporarySspFile_v1* | sspfile/uploadtemporary |
Team
| SOAP | REST |
|---|---|
| GetTeams_v1** | team (get) |
| SetTeams_v1** | team (post) |
User
| SOAP | REST |
|---|---|
| CreateUser_v1** | user/create |
| DeleteUser_v1** | user/{userId} (delete) |
| UpdateUser_v1** | user/{userId} (patch) |
| FindUsers_v1** or FindUsers_v2** | user/find |
| user/{userId}/uploadSignatureImage | |
| GetUserByEmail_v1** | user/{email} |
Version
| SOAP | REST |
|---|---|
| GetVersion_v1 *** | version |
* api calls from the following endpoint: https://demo.esignanywhere.net/api.asmx?WSDL
** api calls from the following endpoint: https://demo.esignanywhere.net/UserManagementApi.asmx?WSDL
*** api calls which are offered by both endpoints
Api calls which are only available with SOAP:
- GetAdHocWorkstepConfiguration_v1
- NotifyEnvelopeWorkstepIsCompleted_v1
- UploadUserFile
Api calls which are only available with REST:
- user/{userId}/uploadSignatureImage
Significant changes
Apart from the different endpoints and the fundamental changes in the syntax (from XML to JSON), there are also the following significant changes if you switch from SOAP to REST.
For this changes please also have a look at the postman tutorial: https://www.esignanywhere.net/esignature-api/tutorial-hello-world/esignanywhere-api-postman-sample/
In the next section you can find a sample for the fundamental changes in the syntax:
The authentication section in SOAP:
<authentications> <authentication> <method>Pin</method> <parameter>1234</parameter> </authentication> </authentications>
would look like the following in REST:
"AuthenticationMethods": [
{
"Method": "Pin",
"Parameter": "1234"
}
]
The authentication
In REST the authentication is transferred in the header. In SOAP there is a separate section for the authentication.
Upload a File
In REST, files are sent as HTTP POST with multipart/form-data encoding of the JSON in the POST body. In SOAP you have to BASE64 encode the file and then you have to add the encoded file in the api call.
Workstep configuration
In SOAP the signature fields are in the section signatureTemplate in REST the signature fields are in the section Tasks. You can find a sample for REST and SOAP in the next section. This sample includes a Click2Sign a Draw2Sign and a Type2Sign.
<signatureTemplate>
<version>1.2.0.2</version>
<positionReferenceCorner>Lower_Left</positionReferenceCorner>
<positionUnits>PdfUnits</positionUnits>
<sig id="1#XyzmoDuplicateIdSeperator#Signature_231ac4b4-f182-e9f0-5323-5b305f31a056">
<TaskDisplayName />
<param name="enabled">1</param>
<positionPage>1</positionPage>
<positionX>71</positionX>
<positionY>612</positionY>
<width>191</width>
<height>80</height>
<param name="positioning">onPage</param>
<param name="req">1</param>
<param name="fd" />
<param name="fd_dateformat">dd-MM-yyyy HH:mm:ss</param>
<param name="fd_timezone">datetimeutc</param>
<DocRefNumber>1</DocRefNumber>
<AllowedSignatureTypes>
<sigType id="a6949584-befc-4eed-ba78-a638930cd68a" type="Picture">
<allowedCapturingMethods>Click2Sign</allowedCapturingMethods>
<StampImprintConfiguration>
<DisplayExtraInformation>1</DisplayExtraInformation>
<DisplayEmail>1</DisplayEmail>
<DisplayIp>1</DisplayIp>
<DisplayName>1</DisplayName>
<DisplaySignatureDate>1</DisplaySignatureDate>
<FontFamily>Times New Roman</FontFamily>
<FontSize>11</FontSize>
</StampImprintConfiguration>
</sigType>
</AllowedSignatureTypes>
</sig>
<sig id="1#XyzmoDuplicateIdSeperator#Signature_477f72ff-de53-f3f3-1bf7-4a9bd42dfd4a">
<TaskDisplayName />
<param name="enabled">1</param>
<positionPage>1</positionPage>
<positionX>71</positionX>
<positionY>516</positionY>
<width>191</width>
<height>80</height>
<param name="positioning">onPage</param>
<param name="req">1</param>
<param name="fd" />
<param name="fd_dateformat">dd-MM-yyyy HH:mm:ss</param>
<param name="fd_timezone">datetimeutc</param>
<DocRefNumber>1</DocRefNumber>
<AllowedSignatureTypes>
<sigType id="de51ac1f-f56d-4baa-95bc-084c4186ff18" type="Picture">
<allowedCapturingMethods>Draw2Sign</allowedCapturingMethods>
<StampImprintConfiguration>
<DisplayExtraInformation>1</DisplayExtraInformation>
<DisplayEmail>1</DisplayEmail>
<DisplayIp>1</DisplayIp>
<DisplayName>1</DisplayName>
<DisplaySignatureDate>1</DisplaySignatureDate>
<FontFamily>Times New Roman</FontFamily>
<FontSize>11</FontSize>
</StampImprintConfiguration>
</sigType>
</AllowedSignatureTypes>
</sig>
<sig id="1#XyzmoDuplicateIdSeperator#Signature_6e62002d-2510-0512-fb7e-085b80e49227">
<TaskDisplayName />
<param name="enabled">1</param>
<positionPage>1</positionPage>
<positionX>71</positionX>
<positionY>420</positionY>
<width>191</width>
<height>80</height>
<param name="positioning">onPage</param>
<param name="req">1</param>
<param name="fd" />
<param name="fd_dateformat">dd-MM-yyyy HH:mm:ss</param>
<param name="fd_timezone">datetimeutc</param>
<DocRefNumber>1</DocRefNumber>
<AllowedSignatureTypes>
<sigType id="745f8cb7-54e8-4ece-88a2-73fd60a29194" type="Picture">
<allowedCapturingMethods>Type2Sign</allowedCapturingMethods>
<StampImprintConfiguration>
<DisplayExtraInformation>1</DisplayExtraInformation>
<DisplayEmail>1</DisplayEmail>
<DisplayIp>1</DisplayIp>
<DisplayName>1</DisplayName>
<DisplaySignatureDate>1</DisplaySignatureDate>
<FontFamily>Times New Roman</FontFamily>
<FontSize>11</FontSize>
</StampImprintConfiguration>
</sigType>
</AllowedSignatureTypes>
</sig>
</signatureTemplate>
"Tasks": [
{
"PositionPage": 1,
"Position": {
"PositionX": 71.0,
"PositionY": 612.0
},
"Size": {
"Height": 80.0,
"Width": 191.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"
}
],
"AllowedSignatureTypes": [
{
"AllowedCapturingMethod": "Click2Sign",
"Id": "54d05592-39d0-45cf-bcf7-89fa92f4c08d",
"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_231ac4b4-f182-e9f0-5323-5b305f31a056",
"DisplayName": "",
"DocRefNumber": 1,
"DiscriminatorType": "Signature"
},
{
"PositionPage": 1,
"Position": {
"PositionX": 71.0,
"PositionY": 516.0
},
"Size": {
"Height": 80.0,
"Width": 191.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"
}
],
"AllowedSignatureTypes": [
{
"AllowedCapturingMethod": "Draw2Sign",
"Id": "4addafe5-3446-4d06-815f-637fada09b1c",
"DiscriminatorType": "SigTypeDraw2Sign",
"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_477f72ff-de53-f3f3-1bf7-4a9bd42dfd4a",
"DisplayName": "",
"DocRefNumber": 1,
"DiscriminatorType": "Signature"
},
{
"PositionPage": 1,
"Position": {
"PositionX": 71.0,
"PositionY": 420.0
},
"Size": {
"Height": 80.0,
"Width": 191.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"
}
],
"AllowedSignatureTypes": [
{
"AllowedCapturingMethod": "Type2Sign",
"Id": "4e4bc9f3-aeb8-4daa-bfc9-882e20027739",
"DiscriminatorType": "SigTypeType2Sign",
"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_6e62002d-2510-0512-fb7e-085b80e49227",
"DisplayName": "",
"DocRefNumber": 1,
"DiscriminatorType": "Signature"
}
]
}
},
Note (Only in SOAP): For every interactive field(signature field, text field, checkbox etc.) you have to add a workstep task.
For example for the three signature fields above you would have to add three tasks within the WorkstepTasks section:
<WorkstepTasks originalSequenceMode="NoSequenceEnforced" SequenceMode="NoSequenceEnforced">
<Task type="SignField" DocRefNumber="1" id="4738" [...] displayName="" required="1" />
[...]
</WorkstepTasks>
In REST the task is already given in the configuration when the signature field is added.
MetaData
You can send the metadata within the workstep configuration in REST. For the metadata please use the XML format. You can find a sample in the next section.
"BasicOptions": {
"Name": "Envelope_Test",
"EmailSubject": "Test",
"EmailBody": "Dear #RecipientFirstName#!\n\nPlease sign this document.",
"EnableReminders": true,
"FirstReminderDayAmount": 1,
"RecurrentReminderDayAmount": 1,
"BeforeExpirationDayAmount": 1,
"MetaDataXml": "<metaData><Tagging doctype=\"INVOICE\"><InvoiceNr>123456</InvoiceNr></Tagging></metaData>
}
SOAP to REST proxy
You can of course continue to send all SOAP calls in the future. To do this, you would have to implement a proxy to transform the SOAP calls into REST calls. Please see the next figure for more information:
| Figure | Description |
|---|---|
 |
|