Migration Guide (SOAP to REST)

This guide shows you all changes you have to take into account when you switch from a SOAP integration to a REST integration.

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