Embedding

By default, DocuSign transactions and workflows are initiated through email. The recipients - known as a remote recipients in this case - use system-generated email links to complete their documents through the simple and intuitive DocuSign Website. Using embedded recipients you can you let users sign or send documents directly through your UI, avoiding the context-switch to email.

Embedded Signing (or Recipient View)

Embedded Signing - or the Recipient View workflow - allows users to sign directly through your app or website. When you embed your recipients you are telling the DocuSign platform your app will generate signing URLs, authenticate your recipients, present the signing request, and re-direct once the transaction is complete.

For browser integrations re-directing or framing can be used to host the signing workflow, for mobile apps (iOS and Android) you should use a webview. The embedded signing workflow is usually accomplished in two steps:

  • Send an envelope with an embedded recipient
  • Generate the recipient signing URL

You can only generate recipient signing links for envelopes that are in sent status. Also note that signing links expire after 300 seconds (5 mins) and are one-time use only, meaning you need to generate a new signing token each time the recipient wants to access the envelope.

Step 1: Send Envelope with Embedded Recipient

The first step is to create and send an envelope with an embedded recipient. To designate a recipient as embedded you simply have to set their clientUserId property, along with the additional recipient properties you normally set like name and email. The clientUserId is a sender-defined value which identifies the embedded recipient and allows a signing URL to be generated for them.

To create and send an envelope with an embedded recipient use the Envelopes: create method by making an http POST request to the following endpoint:

POST /accounts/{accountId}/envelopes

Along with the following request body:

{
    "status": "sent",
    "emailSubject": "Envelope with Embedded Signer",
    "documents": [{
        "documentId": "1",
        "name": "contract.pdf",
        "documentBase64": "base64 document bytes...",
    }],
    "recipients": {
        "signers": [{
            "email": "john@email.com",
            "name": "John Doe",
            "recipientId": "1",
            "clientUserId": "1234"
        }]
    }
}

The recipient is embedded since their clientUserId property, which takes a string, is set to a non-null value. You may only generate signing URLs for recipients who have their clientUserId property set. The above envelope definition generates a typical create envelope response:

{
    "envelopeId": "d1cf4bea-1b78-47ea-b372-746678e3679f",
    "uri": "/envelopes/d1cf4bea-1b78-47ea-b372-746678e3679f",
    "statusDateTime": "2016-06-02T22:57:27.8300000Z",
    "status": "sent"
}

Test this API

Step 2: Generate the Recipient Signing URL

To generate the recipient signing URL call the EnvelopeViews: createRecipient method, using the same identifying recipient information - including the clientUserId - that was sent with envelope. To do this make an http POST request to the following endpoint:

POST /accounts/{accountId}/envelopes/{envelopeId}/views/recipient

With the following request body:

{
    "userName": "John Doe",
    "email": "johndoe@email.com",
    "recipientId": "1",
    "clientUserId": "1234",
    "authenticationMethod": "email",
    "returnUrl": "https://www.docusign.com/devcenter"
}

The recipient information - userName, email, recipientId, and clientUserId - must match the values that were provided when the recipient was first added to the envelope, otherwise an error will be returned. Also note we use the userName property to reference the recipient's name instead of just name.

The authenticationMethod is an enumerated value that indicates the convention used to authenticate the signer. Since, with Embedding, you are telling Docusign that you are handling authentication this is your way of telling the platform how you authenticated the recipient. This information will also be included in the Certificate of Completion, a PDF that is automatically generated for every completed envelope. Lastly, the returnUrl is where the recipient will be re-directed to once signing is complete.

A successful response looks like:

{
    "uri": "https://demo.docusign.net/Signing/startinsession.aspx?t=fd6b9e60-e6f6-4260-a9fc-1f4d2e1973d1&pei=d1cf4bea-1b78-47ea-b372-746678e3679f"
}

Test this API

Determining Recipient Action

Once the embedded signing workflow is complete the recipient is re-directed to the value you provided through the returnUrl parameter. A query parameter in the form of ?event={event_type} is appended to the return url and can be parsed by your app to determine what action the recipient took. For example, if the return url is http://www.acme.com and the recipient signed the document the value would be:

http://www.acme.com?event=signing_complete

There are numerous actions the embedded recipient might take:

  • cancel - the recipient decides to finish later
  • decline - the recipient declines signing
  • exception - a processing error occurs during the signing session
  • fax_pending - if the recipient choses to print, sign and fax back
  • id_check_failed - if authentication was added to the document, this is when the recipient fails
  • session_timeout - the signing session times out when recipient goes idle
  • signing_complete - the recipient completed signing
  • ttl_expired - the token was not used within the timeout period or the token was already accessed
  • viewing_complete - a recipient that does not need to sign completes the viewing ceremony

For additional recommendations on embedding functionality see the optimizing embedded workflow section below.

Embedded Sending (or Sender View)

The Embedded Sending view of an envelope allows users to edit the tabs, documents, recipients, and other settings of draft envelopes before sending them out for approval. Similar to Embedded Signing, your app or website can generate a sending URL and integrate directly into your workflow using a Redirect, Webview, or an iFrame.

To generate the Embedded Sending View you must first create an envelope with a status set to "created", which in turn saves the envelope as a draft in your account. Using the envelopeId of the envelope in a draft state you can make a POST request to the following endpoint to generate the sending URL:

POST /accounts/{accountId}/envelopes/{envelopeId}/views/sender

With the following request body:

{
    "returnUrl": "https://www.docusign.com/devcenter"
}

Just like with the recipient view, the returnUrl property controls where the user is re-directed to once they are done with the Sending View.

A successful response look like:

{
    "uri": "https://demo.docusign.net/Member/StartInSession.aspx?StartConsole=1&t=69838ac2-ab1f-403e-9f32-47a9aa679eca&DocuEnvelope=d1cf4bea-1b78-47ea-b372-746678e3679f&send=1"
}
Test this API

Optimizing Embedded Workflows

For desktop and laptop browser integrations DocuSign recommends the following for improved embedded experiences:

  • Re-direct and let DocuSign take full control of the browser window
  • Framing is fine, but make sure to handle sizing of the frame and use

For mobile browser integrations:

  • Re-direct and let DocuSign take full control of the browser window
  • Pop a new window and handle the completion event
  • If you must, use an iFrame but resize using JavaScript

For mobile and native apps:

  • Use a custom host for the returnUrl: (e.g. http://yourappname/)
  • Return true when receiving URL changes matching your host to handle DocuSign events
  • For iOS, handle returnUrl with webView:shouldStartLoadWithRequest:navigationType
  • For Android, handle returnUrl with WebViewClient.shouldOverrideUrlLoading

API Recipes

In addition to Embedded Signing and Embedded Sending you can also Embed the DocuSign UX directly into your app or website. For example, you could create an "Open DocuSign" button which gives your users full access to their DocuSign accounts, allowing them to do things like change account settings, add users, and more.