Long-lived embedded signing URLs

About half of all applications built on the Docusign System of Agreement platform use an embedded signing session. Embedded signing provides a smooth user experience, since the user does not need to leave the flow of the application.

For many use cases, the signer clicks a button on the application and is then taken to the Docusign signing session. But there are other use cases where a URL will be created that will later be used to open the signing session. 

Since the URL returned by the EnvelopeViews:createRecipient is time-limited and must be used within five minutes, how can an application create a URL that will last longer? A URL that can be sent to signers? 

The answer is to give your signers a customized URL that is handled by your application. When your signer clicks the URL, your application first obtains an embedded signing URL from Docusign and then responds to the signer with a redirect to the URL.

Creating the customized URL

Create a database table in your application with columns:

1. ID

2. url_lookup_guid

3. account_id

4. envelope_id

5. signer_email

6. signer_name

7. signer_clientUserId

8. envelope_expiration_date (optional, see below)

To create a unique URL for an embedded signer:

1. generate a GUID. It will be used as the url_lookup_guid value

2. Create a record in the database table.

3. The URL will be something like: myapp.mycompany.com/sign/url_lookup_guid_value

Creating the embedded signing session

1. The user opens (GET call) the URL you gave them: for example,  myapp.mycompany.com/sign/1234567-1234-1234-123456789

2. Pull out the GUID value from the URL.

3. Look up the record in your database.

4. Use the other values in the record to make a call to EnvelopeViews:createRecipient.

5. Receive the embedded signing URL response to the API call.

6. Redirect the signer to the URL.

7. Remove the database record or mark it as used.

Clearing old database entries

1. As noted above, you can delete database rows once they're used.

2. To clear out entries that were never used, a batch process can check the database each day for obsolete entries where the envelope has expired.Either record the expiration date, or auto-create an insertion date in the database. Then, once your account's default expiration time has been exceeded, make an API call to Docusign to check that the envelope has indeed expired. (Its expiration date may have been extended.)

Notes

• The URLs that you create can last as long as you wish, or until the envelope expires within Docusign, whichever comes sooner.

• The URL will enable the person to sign the envelope, so you'd probably want to include additional signer authentication from Docusign to ensure that the signer is who they say they are.

• Don't use the database's ID as the lookup key, since you want to ensure that someone can't guess the ID of a record. Use a random GUID as the lookup key.

• Your app will need an access token to make the API call to Docusign. Since this is an autonomous task, use the OAuth JWT Grant flow.

• Don't create a new access token per invocation; instead, cache the current access token.

• Since it can take a couple of seconds to create the redirect URL (or more time if you need to obtain a new access token as well), you might want to first return an intermediate page that shows a "please stand by" message and makes an AJAX call to your app to obtain the URL for the redirect.

Let us know your comments! You can comment via this StackOverflow answer.

Additional resources

• Docusign Developer Center

• Docusign Developers YouTube channel

• @DocuSignAPI on Twitter

• Docusign for Developers on LinkedIn

• Docusign Developer Newsletter