August 28, 2026
The Short Answer: Use htmlDefinition, Not documentBase64
To create a responsive HTML document through the DocuSign eSignature REST API, define the document in the documents array of your Envelopes:create request with an htmlDefinition object whose source property contains your page's HTML as plain text — not as a Base64 string. Set documentId to a string such as "1", set the document name, and set fileExtension to "html" (DocuSign's engineering blog also shows working examples with "htm"). Then POST the envelope to /restapi/v2.1/accounts/{accountId}/envelopes. Built this way, the document is routed through DocuSign's Responsive Signing system, and signers on phones and tablets get a web-style signing page that scales to their screen instead of a fixed-layout PDF.
The trap to avoid: passing HTML bytes through documentBase64. DocuSign's developer support team has documented that this routes the document through the normal processing pipeline and does not produce a responsive document; in some accounts it returns an error stating that HTML is not allowed for that call.
One availability caveat: advanced responsive signing — sending HTML directly and using Smart Sections — is available in all developer (sandbox) accounts but only in certain production plans, while basic responsive signing (automatic PDF-to-HTML conversion) is disabled by default and must be enabled by an account administrator. Confirm your production plan's capabilities with DocuSign support, and verify behavior in the sandbox first.
How Responsive Signing Fits Together
DocuSign documents two levels of responsive signing. In basic responsive signing, you supply a PDF (or another supported file type) and DocuSign converts it into a signable HTML document; existing tabs are preserved, anchor tabs stay attached to their text, and the result is stored as an envelope attachment you can retrieve. In advanced responsive signing, you send HTML directly and optionally add Smart Sections. Both produce pages that dynamically resize for a better mobile signing experience than a fixed PDF.
The htmlDefinition object also exposes mobile-specific controls from the API reference: maxScreenWidth, which limits the responsive HTML version to screens at or below a given pixel width (larger screens see the PDF version instead), and showMobileOptimizedToggle, which shows a Mobile-Friendly toggle on mobile devices so signers can switch to the PDF view before finishing.
The Envelope Request: htmlDefinition in Code
The official how-to guide for creating a signable HTML document uses three steps: obtain an OAuth token, build the envelope definition with an htmlDefinition node, and call the eSignature REST API. Here is the request in curl form with placeholder credentials.
```bash
curl -s -X POST "https://demo.docusign.net/restapi/v2.1/accounts/{$ACCOUNT_ID}/envelopes" \
-H "Authorization: Bearer {$JWT}" \
-H "Content-Type: application/json" \
-d @envelope.json
```
The envelope.json body below carries the HTML as text, maps a signer role for tab assignment, and includes one Smart Section definition:
```json
{
"emailSubject": "Your mobile-friendly agreement",
"status": "sent",
"documents": [
{
"documentId": "1",
"name": "agreement.html",
"fileExtension": "html",
"htmlDefinition": {
"source": "
Service Agreement
Terms text here
pricing_table_start
| Plan A |
pricing_table_end
","displayAnchors": [
{
"startAnchor": "pricing_table_start",
"endAnchor": "pricing_table_end",
"removeStartAnchor": true,
"removeEndAnchor": true,
"caseSensitive": true,
"displaySettings": {
"display": "responsive_table_single_column",
"tableStyle": "width:100%;max-width:816px;margin-left:auto;margin-right:auto;",
"cellStyle": "text-align:left;padding:0px;"
}
}
]
}
}
],
"recipients": {
"signers": [
{
"email": "signer@example.com",
"name": "Example Signer",
"recipientId": "1",
"roleName": "Signer"
}
]
}
}
```
Three details matter. First, documentId must be an integer between 1 and 2,147,483,647, encoded as a string without commas; tabs reference the document through it. Second, source is plain text — the how-to guide is explicit that you add your page's HTML directly to the value of source, not Base64. Third, watch your quoting: DocuSign's engineers recommend limiting quotation marks inside HTML definitions and using apostrophes instead, because extra double quotes inside JSON-embedded HTML frequently cause deserialization errors.
After the envelope is created, the signer receives an email with a signing link usable in the DocuSign mobile app or website. When the envelope completes, the signed documents and evidence live in the completed envelope — see the DocuSign certificate of completion and audit trail guide for what to retain. You can also read back stored definitions with GET /restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/html_definitions (EnvelopeHtmlDefinitions:list).
Placing Tabs in an HTML Signing Document
Tabs in responsive HTML documents do not use xPosition/yPosition coordinates. DocuSign's "Setting tabs in HTML documents" guide describes two methods. The first is HTML blocks: each tab type has a corresponding DocuSign HTML tag, configured through attributes such as data-ds-role, data-ds-recipient-id, required, readonly, font-size, and color; attribute values override tab defaults. The second is JSON markers: embed markers containing a tabLabel in the HTML source, and each marker is replaced by the matching tab definition from your API request. Radio tabs are the special case — their markers must include groupName and value properties that map to a radio group.
Two constraints from the same guide will bite you if missed. Only inline styles are reflected in the processed document; styles defined outside the page, such as