Embedded Signing

This topic shows you how to embed a DocuSign signing ceremony in your application.

A person who signs via your application is referred to as an embedded or captive recipient.

A person who signs after receiving an email and authenticates with DocuSign is a remote signer.

The most important difference between remote and embedded recipients is that your application is responsible for authenticating the identity of the signer.

In this example, the same document and tabs used for the Request a Signature via Email example will be used.

First follow the steps in the Request a Signature via Email example, and send the envelope for signing. The email example discusses the document layout, its anchor text, and the tab definitions that are used by the examples.

Next, follow these steps to create the envelope and display the signing ceremony to the embedded signer.

This example uses curl to send requests to DocuSign. As an alternative, you can use the API’s SDKs, available in a variety of languages.

Creating the envelope

The only difference from the JSON request used in the Request a Signature via Email example is the addition of a clientUserId field in the signer recipient object. We will also use the recipientId field to identify the signing recipient in a later step.

"recipients": {
    "signers": [
            "email": "the_nda_signer@mailinator.com",
            "name": "Darlene Petersen",
            "recipientId": "1",
            "routingOrder": "1",
            "clientUserId": "1000",
            "tabs": {

The clientUserId has two purposes:

  • If it is set to a non-null value, it indicates to the DocuSign Signature system that the recipient is an embedded recipient.
  • You must be able to associate the field’s value with the authentication system your application uses. The field will be included in the envelope’s Certificate of Completion. In case of a dispute, you must be able to show how your application authenticated the person.

Prepare the Envelopes: create JSON request

The following steps are the same as in the Request a Signature via Email example. They’re presented as a code block to enable you to easily copy/paste the commands to your computer.

Please see the Request a Signature via Email example for complete explanations of each step

# In a temporary directory...
# Step 1. Download a sample pdf file
curl -s https://docs.docusign.com/assets/example_docs/Mutual_NDA.pdf > Mutual_NDA.pdf
# Step 2. Prepare the Document to send through DocuSign using base64 encoding
base64 Mutual_NDA.pdf -o Mutual_NDA.pdf.base64
# Step 3. Download the envelope definition JSON file
curl https://docs.docusign.com/assets/quickstart/create_envelope_embedded_signing.json > create_envelope_embedded_signing.json
# Step 4. Substitute the pdf file’s contents into the JSON file
sed -e "s/FILE1_BASE64/$(sed 's:/:\\/:g' Mutual_NDA.pdf.base64)/" create_envelope_embedded_signing.json > payload.json

The payload.json file is now ready to be sent to the Envelopes: create method.

Obtain the account id and base URL

All DocuSign Signature REST API requests require a baseUrl. Obtain the baseUrl by using the Authentication: login) method.

curl https://demo.docusign.net/restapi/v2/login_information  \
     -k -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H 'X-DocuSign-Authentication: { 

# The response
  "loginAccounts": [
      "name": "NewCo",
      "accountId": "1703272",
      "baseUrl": "https://demo.docusign.net/restapi/v2/accounts/000000",
      "isDefault": "true",
      "userName": "API Tester",
      "userId": "1470ff66-f92e-4e8e-ab81-8c46f140da37",
      "email": "name@example.com",
      "siteDescription": ""

The result shows that this set of client authentication credentials has access to one account.

It is not uncommon for a set of credentials to have access to more than one account. Your application should enable the accountId to be selected or set by the user or administrator, as appropriate.

Send the envelope request

Send the Envelopes: create request using the payload.json file you prepared earlier. The URL for your request is the baseUrl plus /envelopes

curl -k -X POST -d @payload.json \
                  -H "Accept: application/json" \
                  -H "Content-Type: application/json" \
                  -H 'X-DocuSign-Authentication: { 
                        "IntegratorKey":"230546a7-9c55-40ad-8fbf-af205d5494ad"}' \

# The response
  "envelopeId": "4280f274-bfee-419b-9514-b218b7eeda08",
  "uri": "/envelopes/4280f274-bfee-419b-9514-b218b7eeda08",
  "statusDateTime": "2016-06-13T07:54:29.9970000Z",
  "status": "sent"

The Recipient View url

After the signer has authenticated with your application, and is ready to sign, obtain the recipient view url for the signer. Use the EnvelopeViews: createRecipient method.

The method requires:

  • envelopeId – from the Envelopes: create response. The value is used in the method’s url.
  • returnUrl – the url that the signer’s browser will be re-directed to after the signer has finished. The url should be hosted by your application. An https url is recommended. For this example, to see the url’s format, we’ll use the diagnostic url https://httpbin.org/get from https://httpbin.org.
  • authenticationMethod – how your app authenticated the signer. Available values include Email, HTTPBasicAuth, PaperDocuments, and Password. See the method’s page for additional options.

In addition, the method requires that you identify which person will be signing. There are multiple ways to identify a signer. The simplest is to use the following fields, all of which you provided in the Envelopes: create call. The values must be the exact same as what were used in the Envelopes: create call.

  • clientUserId
  • email
  • recipientId
  • userName

Other techniques and fields for identifying the recipient are documented with the method.

The method’s url is the baseUrl plus /envelopes/the_envelope_id/views/recipient

Request the recipient view

curl -k -X POST  \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H 'X-DocuSign-Authentication: { 
          "IntegratorKey":"230546a7-9c55-40ad-8fbf-af205d5494ad"}' \
    -d '{"authenticationMethod":"email",
         "userName":"Darlene Petersen"}' \

# Response
  "url": "https://demo.docusign.net/Signing/startinsession.aspx?t=f0cbd54c-47cd-4e3f-9a7c-056302985c9d"

The successful response provides the URL for the recipient’s view.

Signing Ceremony

Redirect the user’s browser to the recipient view URL.

Note: Please do not use an iFrame to hold the recipient view. Redirect the signer’s browser. This is especially important for people who will sign via a mobile device. See “Maintaining State,” below, for techniques that obviate the need for an iFrame.

After the signer has completed the signing ceremony, DocuSign will redirect the signer’s browser back to your application, using the returnUrl you specified in the EnvelopeViews: createRecipient method.

When the browser is redirected to your app, an event query parameter will be appended to your URL.

The event parameter will have one of the following values:

  • cancel (recipient canceled the signing operation)
  • decline (recipient declined to sign)
  • exception (an exception occurred)
  • fax_pending (recipient has a fax pending)
  • session_timeout (session timed out)
  • signing_complete (signer completed the signing ceremony)
  • ttl_expired (the time to live timer expired)
  • viewing_complete (recipient completed viewing the envelope)

After the Signing Ceremony

After the user ends the signing ceremony and the signer’s browser has been redirected to your app, the best practice is to immediately return an html page to the signer’s browser. The page is referred to as a working page since it shows the message “Working…” to the signer. It could also include a countdown or spinner.

The working page should indicate that signing has completed, and that the signed document is being processed.

The working page should also make an Ajax call to your application. Your app, in response to the Ajax call, should conclude your app’s processing of the signed document: updating your database, etc.

When the Ajax call returns to the signer’s browser, the signer can continue with their other tasks.

The benefit of this control flow is to provide the best user experience and quickest responses to the signer after she has completed signing the document.

You do not want the signer to wait after they have pressed the “Finished” button on the DocuSign signing ceremony page.

An alternative that also provides a great UX is to use the DocuSign webhook facility to notify your app that the envelope was signed or declined. See the Status and Events topic.

Maintaining state

When DocuSign redirects to your app, and your app makes an Ajax call to itself to process the results of the signing ceremony, how can your app maintain state? How does your app know which envelope has been signed, and by whom?

Several techniques are available

  • Your app can set a cookie. The cookie will then be included when the signer’s browser is redirected to your app and when an Ajax call is made. Many application stacks include a secure session facility which uses encrypted cookies.
  • Your app can include its own query parameters in the returnUrl field. When the redirect is sent, the event parameter will be added to any preexisting query parameters. If you use this technique, don’t use a guessable session parameter since malware might try to hijack someone’s session by guessing their session parameter. You will also want to guard against replay attacks.
  • When creating the envelope, you can include your own data in an Envelope Custom Field. Then, when the DocuSign webhook notifies your listener that the envelope has been signed or rejected, your software can recover its state by looking in the custom field.

Pinging your app

The signer can take a long time to complete the signing ceremony. The EnvelopeViews: createRecipient method includes an optional feature to ping your app while the signer is interacting with DocuSign. See the pingUrl and pingFrequency fields in the method’s body object for more information.

Time to Live

The URL for the recipient’s view is only valid for a minute or so. Therefore the signer’s browser must be immediately redirected to the URL. If you want a longer-lived URL for the signer to use, the URL must be provided by your app. When the signer uses your URL, redirect them to a fresh recipient’s view URL from the DocuSign platform.