From the Trenches: Please sign responsively

Customers have been contacting Docusign Developer Support lately for help using HTML documents. Docusign allows you to add HTML documents to your envelopes in our eSignature REST API, just like other documents, by passing the document as Base64 bytes. This approach does not take full advantage of our advanced support for HTML documents however. HTML documents can also be used to create envelopes that support automatic sizing on mobile devices. Docusign calls this feature Responsive Signing. Docusign offers developers the ability to add collapsable sections to responsive documents using Smart Sections. One of the lesser known features of our Smart Sections technology is the ability to not only add Docusign tabs via HTML definitions, but also add in extra attributes to your HTML source directly. 

To get started, consult our esign101 concepts guide Setting tabs in HTML documents. 

Note: Before you get started, Responsive Signing disallows a number of  CSS and HTML elements for security reasons. Make sure the elements you’re planning on using are supported, or you may quickly run into problems; see the guide for a list of allowed HTML elements and attributes as well as CSS properties.

Define your documents as responsive

The standard JSON for defining a document using a Base64 string looks like this:

{
  "documentBase64": "bytes omitted",
  "documentId": "1",
  "fileExtension": "pdf",
  "name": "Test.pdf"
}

This call does not always create a responsive document. It does not route through our Responsive Signing system; instead, it routes through the normal document processing system. This API call results in a nonresponsive document. The HTML definition may populate as expected but without applying Smart Sections or tabs. In some cases the API sender will see an error stating that HTML is not allowed to be supplied via your call. If you encounter the latter issue, you can reach out to customer support to see about having the feature enabled for you.

Responsive HTML documents need to be declared using an htmlDefinition object and source attribute instead of just a documentBase64 attribute. The simplest JSON for defining a responsive HTML document has the following structure.

{
  "documentId": "1",
  "fileExtension": "htm",
  "htmlDefinition": {
    "source": ""
  },
  "name": "TestFile.html"
}

Notice that you use the htmlDefinition object and that you pass the source attribute as text, not as a Base64 string or a byte array. This call creates a responsive document.

Smart Sections

The Smart Section attributes essentially place borders on the envelope’s documents that are meant for reorienting to the tablet or mobile device on which they’re displayed. These attributes are declared via displayAnchors that are placed in the JSON of the htmlDefinition in your API call.

"htmlDefinition": {
  "displayAnchors": [
    {
      "startAnchor": "responsive_table_start",
      "endAnchor": "responsive_table_end",
      "removeStartAnchor": true,
      "removeEndAnchor": true,
      "caseSensitive": true,
      "displaySettings": {
        "display": "responsive_table_single_column",
        "tableStyle": "margin-bottom: 20px;width:100%;max-width:816px;margin-left:auto;margin-right:auto;",
        "cellStyle": "text-align:left;border:solid 0px #000;margin:0px;padding:0px;"
      }
    }
  ],
  "source": ""
},

Adding tabs in Smart Sections

The htmlDefinition object can also be used to define Docusign tabs and assign them to the role of a particular recipient. Tabs can be added inline in the HTML as either embedded JSON or inline HTML. See Setting tabs in HTML documents.

When assigning recipient tabs via the htmlDefinition object, you need to supply a role name for the tab to map to the correct recipient. You can do this either in the form of a general envelope definition as a server template, which would be in your Templates tab within Docusign, or as part of a composite template. In this case, I’m adding it in via a general envelope definition.

"recipients": {
  "signers": [
    {
      "email": "example@email.com",
      "name": "Example Signer",
      "recipientId": "1",
      "roleName": "Signer",
    }
  ]
}

Note: If you have the Document Visibility feature enabled, one tab will be required per signer. 

Notice in these definitions that this signer’s role name is set to "Signer". Matching the roleName with the roleName in the inline tab definitions allows the developer to use the API call on any accounts that are enabled for Responsive Signing and Smart Sections without needing the overhead of a Docusign template. 

Here’s an example of an inline HTML tab with the role property set:

<ds-date-signed data-ds-role="Signer"></ds-date-signed>

Now, let’s say that you don’t want the standard date signed tab; you want to make it bigger and redder. What you’ll need to do is add in two attributes, again from the guide, which are font-size and color. These attributes will need to be added as embedded style properties in the following HTML format:

<ds-date-signed data-ds-role="Signer" style='\"color:brightred;font-size:32px;\"'></ds-date-signed>

Now, to bring this all together, you’re going to need to add your recipient information, htmlDefinition, and displayAnchors together to create your overall envelope definitions.

{
  "recipients": {
    "signers": [
      {
        "name": "Example Signer",
        "roleName": "Signer",
        "email": "example@email.com",
        "recipientId": "1",
        "routingOrder": "1",
        "tabs": null
      }
    ]
  },
  "status": "sent",
  "emailSubject": "Responsive HTML Document",
  "documents": [
    {
      "documentId": "1",
      "name": "responsive.html",
      "htmlDefinition": {
        "displayAnchors": [
          {
            "startAnchor": "responsive_table_start",
            "endAnchor": "responsive_table_end",
            "removeStartAnchor": true,
            "removeEndAnchor": true,
            "caseSensitive": true,
            "displaySettings": {
              "display": "responsive_table_single_column",
              "tableStyle": "margin-bottom: 20px;width:100%;max-width:816px;margin-left:auto;margin-right:auto;",
              "cellStyle": "text-align:left;border:solid 0px #000;margin:0px;padding:0px;"
            }
          }
        ],
        "source": "
                  
                      <title>Test Page</title><p>Sample Text<br><br><br><br><br><br><br><br><ds-date-signed data-ds-role="Signer"></ds-date-signed><br><br><ds-date-signed data-ds-role="Signer" style='\"color:brightred;font-size:32px;\"'></ds-date-signed><br><br>"
      }
    }
  ]
}</p>

Here are the results (envelope viewed in Correct mode in the Docusign eSignature application):

One last piece of advice that I can give you is to pay attention to your overall JSON structure. You’ll notice pretty quickly that if you’re supplying your envelope definitions in a JSON format, extra quotation marks can cause problems that resolve to deserialization errors. The best practice is to limit yourself from using quotations specifically within the HTML definitions, using an apostrophe instead. If you have additional questions, feel free to reach out to Customer Support.

Additional resources

• Docusign Developer Center

• @DocuSignAPI on Twitter

• Docusign for Developers on LinkedIn

• Docusign for Developers on YouTube

• Docusign Developer Newsletter