From the Trenches: What time was it?

The Docusign eSignature REST API always uses UTC time. If you make a GET API call to retrieve an envelope’s details, the time included in the response is in UTC. Users who view envelopes in the eSignature web application, however, will have multiple variations on how timestamps show up for them. Developer Support has had several conversations with developers who were trying to understand the ways time is presented in Docusign. This article will explain the variations.

For my example, Green Beard is a user who lives in Hawaii. The administrator for the account is Apex Geoff, who lives on the US West Coast. The administrator has set the account Regional Settings to the following:

Greenbeard sends an envelope to Apex Geoff. Both are signers and both sign the envelope.

Apex Geoff might use the eSignature REST API to get envelope information. He could get the envelope information using an envelopeId or by making an API call, providing from_date and to_date query parameters. These would be provided in UTC date format. Likewise, the response will use UTC dates.

This is a snippet of the REST API GET Envelope response for this envelope once the envelope is completed:

"emailSubject": "Please Docusign: _Test.pdf",
"envelopeId": "290d1b34-xxxx-xxxx-xxxx-294cc2eb049e",
"signingLocation": "online",
"customFieldsUri": "/envelopes/290d1b34-xxxx-xxxx-xxxx-294cc2eb049e/custom_fields",
"notificationUri": "/envelopes/290d1b34-xxxx-xxxx-xxxx-294cc2eb049e/notification",
"enableWetSign": "true",
"allowMarkup": "false",
"allowReassign": "true",
"createdDateTime": "2022-07-15T00:08:16.1600000Z",
"lastModifiedDateTime": "2022-07-15T00:13:05.8900000Z",
"deliveredDateTime": "2022-07-15T00:14:50.7600000Z",
"initialSentDateTime": "2022-07-15T00:13:07.4530000Z",
"sentDateTime": "2022-07-15T00:14:23.8030000Z",
"completedDateTime": "2022-07-15T00:15:20.3370000Z",
"statusChangedDateTime": "2022-07-15T00:15:20.3370000Z",

The image below shows Apex Geoff viewing the same envelope’s history. He sees the time zone is Pacific. He has not set a time zone in his preferences, so the time zone comes from his computer.

The next image shows Green Beard’s view of Envelope History for this same envelope. In his user preferences he has chosen Hawaii as his time zone and a 24-hour time display format.

This image below shows the Certificate of Completion (COC). It is the same for both Apex Geoff and Greenbeard or any other viewer. Note that the time zone stamped on the COC is (UTC-10:00) Hawaii. Since Greenbeard is the sender of the envelope, the COC is written in his time zone as defined in his preferences.

To complicate the story of this envelope more, we will assume that Apex Geoff has a legacy Connect setup with a listener in New York. Years ago, a former admin on Apex Geoff’s account asked Docusign to set the timezone for Connect webhook requests to Eastern time. This is a setting Docusign support must set. Consequently, the XML returned for the legacy Connect listener shows Eastern Time.

<envelopeid>290d1b34-xxxx-xxxx-xxxx-294cc2eb049e</envelopeid>
...
<created>2022-07-14T20:08:16.1600</created><sent>2022-07-14T20:51:39.907</sent>

Apex Geoff also has a modern REST API V2.1 Connect configuration. That webhook shows the same UTC timestamps same as our initial REST API Get Envelope call:

"envelopeId": "290d1b34-xxxx-xxxx-xxxx-294cc2eb049e",
...
"createdDateTime": "2022-07-15T00:08:16.1600000Z",
"sentDateTime": "2022-07-15T00:14:23.8030000Z",

At this point you may be wondering, or desperately hoping, that there is a way to set up one time zone across all of these interfaces—and happily, there is! It is not something that a programmer can do in isolation, however. The setup requires the Docusign administrator in the Docusign web app to set the time zone to (UTC) Monrovia, Reykjavik and to clear the “Allow users to set their own Time Zone and Data Format” checkbox.

Note: Do not choose (UTC) Dublin, Edinburgh, Lisbon, London as that time changes in the summer.

The Administrator should set the Regional Settings on the account as follows:

Once that change is made, Green Beard and Apex Geoff will both see the same timestamps in the Envelope History as in the REST API and Connect Webhooks using the REST API data format. The COC in our example will not change, but future envelopes will all reflect UTC time on the COC.

If after making this change you notice any legacy XML Connect Requests with odd time zones, then contact Docusign Support.

Conclusion

In this article I showed the ways time zones may vary in the timestamps on envelopes when viewed by different users, in the eSignature REST API and possibly in older Connect webhooks. It is useful to understand this time stamping even if you decide not to force your users all to UTC time. It is also important for some businesses to make the settings changes that enforce one time zone for all.

Additional resources

• Docusign Developer Center

• @DocuSignAPI on Twitter

• Docusign for Developers on LinkedIn

• Docusign for Developers on YouTube

• Docusign Developer Newsletter