...

Conceptual Changes

• The former option to use insecure organizationTokens (after they had been explicitely enabled on organization level) has been removed.
  Authentication 
• All namings in the API, on method level and inside the models, have been reviewed (and most of them have been changed)
  because we think consistent and simple wording helps to speed up the learning courve of the API users
  
  • In API v6, we are calling elements as it is common in workflow context
  • We improved to get a consistent naming within the API
  • In consideration of clean-code principles, we tried to use "positive-wording" for boolean properties as much as possible
  • Where applicable, the naming of elements in the API is in sync with the naming in the eSignAnyWhere Web UI (in English language)
• We reviewed all default-values
  because with reasonable defaulting many elements don't need to be specified by the user of the API
• We removed historic relicts that come from technical architecture (e.g. „workstepConfiguration“)
  because API users shouldn't burn time by understanding internal concepts of our platform
• The API is no longer using „abstract types“ and the DiscriminatorType element in the API, but include the full structure in the method's model directly now
  because we wanted to focus on compatibility with various REST API code generators
• We are using only the verbs GET and POST; and strictly avoid using PUT, PATCH, DELETE and other HTTP verbs
  again for simplicity, but also to avoid issues with some coding platforms and infrastructure configurations where customers reported issues in the past.
• Clear rule for parameters in API calls:
  • in GET calls, the parameters are part of the URI path.
  • in POST calls, there are NO parameters in the URI path; all parameters are in the HTTP request body.
• Clear rules on datatype formats, e.g.:
  
  • Dates consistently following RFC 3339 Internet Date/Time Format "full-date" type
    e.g. 2022-11-25
  • Timestamps consistently following RFC 3339 Internet Date/Time Format "date-time" type
    e.g. 2022-11-25T09:11:12Z. Mind that a timezone information is mandatory, and Z can be used for "Zulu Time" (i.e. UTC+0)
  • Color values always as an html colorcode string (#rrggbb), e.g. #ff0000 for red

For the more detailled view on changes, where we are referring to old naming and the new replacement, we use following notation in this document:

• Old terminology is formatted in bold-italic
• New terminology is formatted in bold.

Global Naming Changes

We take into account that the words "whitelist" and "blacklist" can be perceived as offensive and hurtful words. It has never been our intention to imply discriminatory or other-valued meanings in the use of these terminologies beyond the purely technical interpretation of including or excluding a subset of parameters from larger sets. We have changed our terminology to "allowlist" and "blocklist" to reflect the worldwide discussion of these terms over the past two years, or are now using descriptive namings for an inclusion lists such as in the ActionCallbackSelection.

In an eSignAnyWhere Envelope, we are now using the term "activity" instead of "recipient". The term "recipient" didn't work gracefully for situations where the "recipient" was just a background service activity such as an "automatic signing" or "automatic sealing" activity. We follow the terminology borrowed from the Business Process Modelling Notation (BPMN), as we consider an envelope as being processed in a signature workflow. 

To emphasize the global aspect of the solution, we have adapted terminologies so that they are suitable for worldwide use. One example is the division of the name into the firstName and lastName, which is not common in every region of the world. Based on common recommendations, we are now using the terms givenName and surname.

Envelope Status Enumeration

The envelope status values have been reviewed, and status values are now aligned with the status value shown in the WebUI.

...

Conceptual Changes

• The former option to use insecure organizationTokens (after they had been explicitely enabled on organization level) has been removed.
  Authentication 
• All namings in the API, on method level and inside the models, have been reviewed (and most of them have been changed)
  because we think consistent and simple wording helps to speed up the learning courve of the API users
  
  • In API v6, we are calling elements as it is common in workflow context
  • We improved to get a consistent naming within the API
  • In consideration of clean-code principles, we tried to use "positive-wording" for boolean properties as much as possible
  • Where applicable, the naming of elements in the API is in sync with the naming in the eSignAnyWhere Web UI (in English language)
• We reviewed all default-values
  because with reasonable defaulting many elements don't need to be specified by the user of the API
• We removed historic relicts that come from technical architecture (e.g. „workstepConfiguration“)
  because API users shouldn't burn time by understanding internal concepts of our platform
• The API is no longer using „abstract types“ and the DiscriminatorType element in the API, but include the full structure in the method's model directly now
  because we wanted to focus on compatibility with various REST API code generators
• We are using only the verbs GET and POST; and strictly avoid using PUT, PATCH, DELETE and other HTTP verbs
  again for simplicity, but also to avoid issues with some coding platforms and infrastructure configurations where customers reported issues in the past.
• Clear rule for parameters in API calls:
  • in GET calls, the parameters are part of the URI path.
  • in POST calls, there are NO parameters in the URI path; all parameters are in the HTTP request body.
• Clear rules on datatype formats, e.g.:
  
  • Dates consistently following RFC 3339 Internet Date/Time Format "full-date" type
    e.g. 2022-11-25
  • Timestamps consistently following RFC 3339 Internet Date/Time Format "date-time" type
    e.g. 2022-11-25T09:11:12Z. Mind that a timezone information is mandatory, and Z can be used for "Zulu Time" (i.e. UTC+0)
  • Color values always as an html colorcode string (#rrggbb), e.g. #ff0000 for red

For the more detailled view on changes, where we are referring to old naming and the new replacement, we use following notation in this document:

• Old terminology is formatted in bold-italic
• New terminology is formatted in bold.

Global Naming Changes

We take into account that the words "whitelist" and "blacklist" can be perceived as offensive and hurtful words. It has never been our intention to imply discriminatory or other-valued meanings in the use of these terminologies beyond the purely technical interpretation of including or excluding a subset of parameters from larger sets. We have changed our terminology to "allowlist" and "blocklist" to reflect the worldwide discussion of these terms over the past two years, or are now using descriptive namings for an inclusion lists such as in the ActionCallbackSelection.

In an eSignAnyWhere Envelope, we are now using the term "activity" instead of "recipient". The term "recipient" didn't work gracefully for situations where the "recipient" was just a background service activity such as an "automatic signing" or "automatic sealing" activity. We follow the terminology borrowed from the Business Process Modelling Notation (BPMN), as we consider an envelope as being processed in a signature workflow. 

To emphasize the global aspect of the solution, we have adapted terminologies so that they are suitable for worldwide use. One example is the division of the name into the firstName and lastName, which is not common in every region of the world. Based on common recommendations, we are now using the terms givenName and surname.

Envelope Status Enumeration

The envelope status values have been reviewed, and status values are now aligned with the status value shown in the WebUI.

Disposable Certificate Enumeration

Please see the following changes referring to the identification types and the document types for disposable certificate:

Identification type

Document type

*Not supported with api v6 and UI - but still available with older api versions than api v6.

...

Complexity Reduction

Structural Changes for Bulk Sending via API & for managing parent envelopes resulting from bulk-sending

...

• Upload was changed from POST /v4/sspfile/uploadtemporary to POST /v6/file/upload
• Delete was changed from DELETE v4/sspfile/disposefile/{sspFileId} to /v6/file/delete with the fileId in the method's body data (JSON model)

Team

Instead of POST /v4/team, the method which allows changing the entire team configuration of an organization is now called POST v6/team/replace. The additional path component allows to introduce other POST methods on team level in the future.

Templates

The method GET /v5/envelope/{templateId}/copyFromTemplate was replaced by 2 methods: First of all use POST /v6/template/createdraft to create a new draft based on the template, and in a 2nd step use POST /v6/draft/send to make the draft an envelope.

User Management

Just a small renaming applied for /v5/userById/{userId}. Its new name is GET /v6/user/{userId}.

• Upload was changed from POST /v4/sspfile/uploadtemporary to POST /v6/file/upload
• Delete was changed from DELETE v4/sspfile/disposefile/{sspFileId} to /v6/file/delete with the fileId in the method's body data (JSON model)

Team

Instead of POST /v4/team, the method which allows changing the entire team configuration of an organization is now called POST v6/team/replace. The additional path component allows to introduce other POST methods on team level in the future.

Templates

The method GET /v5/envelope/{templateId}/copyFromTemplate was replaced by 2 methods: First of all use POST /v6/template/createdraft to create a new draft based on the template, and in a 2nd step use POST /v6/draft/send to make the draft an envelopeThe functionality of GET /v5/userByEmail/{email} (which is similar to the old but deprecated GET /v5/user/{email} ) is now covered by the POST /v6/user/find method.

System

To check the eSignAnyWhere version, also often used to perform a system availability check, the method GET /v4/version was moved into a group of "system" related methods and therefore changed to GET /v6/system/version

...

Instead of the API v5 "DocumentOptions" in the Steps element, document visibility is now managed in the "VisibilityOptions" of the Activity. The structure is very similar, but as mentioned above, the DocumentNumber now references to a defined number which is set in the Documents array instead of an implicit numbering based on array position.

Overview

Image RemovedImage Added

Comparison

Figure	Detailed description

Image Removed

Image Added

Reminders are now configurable in the section "ReminderConfiguration" instead of directly in the envelope description Additionally following reminder configurations can be set: Enabled FirstReminderInDays ReminderResendIntervalInDays BeforeExpirationInDays Expiration can be be configured in the section "ExpirationConfiguration" instead of directly in the envelope description Additionally following expiration settings are available: ExpirationInSecondsAfterSending ExpirationDate Callback configurations can be set in the "CallbackConfiguration" section Please note the following: All available callbacks can be disabled or enabled Email configurations can be found in the section "EmailConfiguration" The section "Steps" which included the workstep configuration, authentication methods etc. was renamed to "Activities"

Signature Configuration

For automatic remote signatures, specifying the resulting stamp imprint appearance with on/off switches (DisplayExtraInformation, DisplayEmail, DisplayTransactionId, DisplayTransactionToken, DisplayPhoneNumber, DisplayIp, DisplayName, DisplaySignatureDate) is no longer supported. Compared to an APIv5 integration, all those fields are now ENABLED. To keep the API simpler, we decided to remove this functionality as the Stamp Imprint Configuration feature meanwhile offers more powerful options and still allows to hide single data rows.

...