Migration Guide - SOAP to REST

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

https://demo.esignanywhere.net/Api/v##latestVersion##/

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
	Direct access via the SOAP interface A SOAP call is sent which is transformed into a REST call via proxy