Blog
Home/

From the Trenches: Please sign responsively

Author Geoff Pfander
Geoff PfanderSenior Developer Support Engineer
Summary5 min read

Walk through the process of adding an HTML document for responsive signing via the eSignature REST API.

    • Define your documents as responsive
    • Smart Sections
    • Adding tabs in Smart Sections
    • Additional resources

    Table of contents

    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):

    Formatting tabs using HTML and CSS

    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

    Author Geoff Pfander
    Geoff PfanderSenior Developer Support Engineer

    Beginning in the 1990s, Geoff's engineering career has followed the evolution of COM, Java and .NET on the machine and SOAP and REST in the cloud. Currently the Developer Support team's subject matter expert for the Apex Toolkit, Geoff has extensive experience as an engineer in support, test, and sales. You can find him on LinkedIn.

    More posts from this author

    Related posts

    • Streamline End-to-End Agreement Management with Docusign: A Developer Overview
      Developers

      Streamline End-to-End Agreement Management with Docusign: A Developer Overview

      Author Larry Jin
      Larry Jin
    • Fast-Track Your Extension Apps with Reference Implementations

      Fast-Track Your Extension Apps with Reference Implementations

      Author Karissa Jacobsen
      Karissa Jacobsen
    Streamline End-to-End Agreement Management with Docusign: A Developer Overview

    Streamline End-to-End Agreement Management with Docusign: A Developer Overview

    Author Larry Jin
    Larry Jin
    Fast-Track Your Extension Apps with Reference Implementations

    Fast-Track Your Extension Apps with Reference Implementations

    Author Karissa Jacobsen
    Karissa Jacobsen

    Discover what's new with Docusign IAM or start with eSignature for free

    Explore Docusign IAMTry eSignature for Free
    Person smiling while presenting