> You are reading the Docusign Developer Documentation. For clean Markdown of any page, append .md to the page URL. > > Documentation indexes by section: > - APIs and SDKs: https://docusign.docs.buildwithfern.com/docs/llms.txt > - Platform 101: https://docusign.docs.buildwithfern.com/platform/llms.txt > - Extension Apps: https://docusign.docs.buildwithfern.com/extension-apps/llms.txt > - Docusign CLI: https://docusign.docs.buildwithfern.com/docusign-cli/llms.txt > > Authentication (OAuth, JWT Grant, M2M): https://docusign.docs.buildwithfern.com/platform/auth > Webhooks and Connect: https://docusign.docs.buildwithfern.com/platform/webhooks > > OpenAPI specifications: https://docusign.docs.buildwithfern.com/openapi.json > MCP server: https://docusign.docs.buildwithfern.com/_mcp/server # How to create a signable HTML document > Describes how to create a signable HTML document used for the Responsive Signing feature This topic demonstrates how to send HTML code directly to create a document for responsive signing. The Docusign *advanced responsive signing* feature enables you to use HTML pages as signing documents in an envelope. > **Note** > > Run this code example from our [Quickstart](/docs/esign-rest-api/quickstart) or launcher projects: [Bash](https://github.com/docusign/code-examples-bash), [C#](https://github.com/docusign/code-examples-csharp), [Java](https://github.com/docusign/code-examples-java), [Node.js](https://github.com/docusign/code-examples-node), [PHP](https://github.com/docusign/code-examples-php), [PowerShell](https://github.com/docusign/code-examples-powershell), [Python](https://github.com/docusign/code-examples-python), or [Ruby](https://github.com/docusign/code-examples-ruby). ## Required data Running the code in this how-to requires this data: | Data element | Description | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | \{API_ACCOUNT_ID} | A [GUID](http://guid.one/) value that identifies your account. This value is automatically generated by Docusign for any account you create. Copy the value from the **API Account ID** field on the [Apps and Keys](https://admindemo.docusign.com/authenticate?goTo=appsAndKeys) page. | | \{BASE_PATH} | A string value that forms the root of the URL required to make API calls. The base path value in the example code is set to target the developer environment at https\://\/restapi Where \ is demo.docusign.net for the developer environment and is the result of the GetUserInfo call in production. | | \{DOCUMENT_HTML} | The HTML source for the document you will create. | ## Step 1. Obtain your OAuth token To make the API call shown in this how-to, you need a valid OAuth access token. Docusign supports access tokens for three different recommended OAuth grant types: Public Authorization Code Grant, Confidential Authorization Code Grant, and JSON Web Token (JWT) Grant. Choose the OAuth grant type appropriate for your scenario. > **Note** > > See [Confidential Authorization Code Grant](/platform/auth/authcode#confidential-authorization-code-grant) for guidance on your options to get an Confidential Authorization Code Grant OAuth token. ![Three icons that represent the three methods a user can use to obtain an OAuth token: JSON Web Token (JWT), Public Authorization Code Grant (ACG), and Confidential Authorization Code grant](/_fern-files/_img/64f473773042ee439449a096bf7673292b1585b86a4ccc55f82ba0dda41f61a1.webp) ## Step 2. Create the envelope definition In the JSON request body for a standard [Envelopes:create](/docs/esign-rest-api/reference/envelopes/envelopes/create) method call, ensure that you have at least one document defined in the request’s `documents` block. For each HTML document in the envelope, add an `htmlDefinition` node. Within the `htmlDefinition` node, insert another node called `source`. Add your page’s HTML to the value of `source`. The sample shows a `documents` node of a request to create a new signable HTML document. > **Warning** > > If the HTML code contains `` elements with the `src` attribute set to a path or URL, those images will not be displayed. Images in HTML must be encoded in Base64 format, as shown in the example below: ```text Base64 encoded image ``` See the [API Reference](/docs/esign-rest-api/reference/envelopes/envelopes/create#schema__envelopedefinition_documents_htmldefinition) for the full list of request parameters and configurable options. **`Bash`** ```bash title="Bash" html_with_tabs=`cat $html_document_path \ | sed 's/sn1//g' \ | sed 's/l1q//g' \ | sed 's/l2q//g' \ | sed 's/\\"/\\\\\\\\"/g'` printf \ '{ "emailSubject": "Example Signing Document", "documents": [ { "name": "Lorem Ipsum", "documentId": "1", "htmlDefinition": { "source": "'"${html_with_tabs}"'", } } ], "recipients": { "signers": [ { "email": "'"${SIGNER_EMAIL}"'", "name": "'"${SIGNER_NAME}"'", "recipientId": "1", "routingOrder": "1", "clientUserId": "1000", "signerRole": "Signer", "tabs": { "formulaTabs": [ { "anchorString": "/l1e/", "anchorUnits": "pixels", "anchorXOffset": "105", "anchorYOffset": "-8", "disableAutoSize": "false", "font": "helvetica", "fontSize": "size11", "formula": "[l1q] * 5", "locked": "true", "required": "true", "roundDecimalPlaces": "0", "tabLabel": "l1e" }, { "anchorString": "/l2e/", "anchorUnits": "pixels", "anchorXOffset": "105", "anchorYOffset": "-8", "disableAutoSize": "false", "font": "helvetica", "fontSize": "size11", "formula": "[l2q] * 150", "locked": "true", "required": "true", "roundDecimalPlaces": "0", "tabLabel": "l2e" }, { "anchorString": "/l3t/", "anchorUnits": "pixels", "anchorXOffset": "105", "anchorYOffset": "-8", "bold": "true", "disableAutoSize": "false", "font": "helvetica", "fontSize": "size11", "formula": "[l1e] + [l2e]", "locked": "true", "required": "true", "roundDecimalPlaces": "0", "tabLabel": "l3t" }, ], } } ], "carbonCopies": [ { "email": "'"${CC_EMAIL}"'", "name": "'"${CC_NAME}"'", "recipientId": "2", "routingOrder": "1" } ] }, "status": "sent" }' >> $request_data ``` **`C#`** ```csharp title="C#" private static EnvelopeDefinition MakeEnvelope( string signerEmail, string signerName, string ccEmail, string ccName, string signerClientId) { int price1 = 5; int price2 = 150; FormulaTab formulaTab1 = new FormulaTab { Font = "helvetica", FontSize = "size11", FontColor = "black", AnchorString = "/l1e/", AnchorYOffset = "-8", AnchorUnits = "pixels", AnchorXOffset = "105", TabLabel = "l1e", Formula = $"[l1q] * {price1}", RoundDecimalPlaces = "0", Required = "true", Locked = "true", DisableAutoSize = "false", }; FormulaTab formulaTab2 = new FormulaTab { Font = "helvetica", FontSize = "size11", FontColor = "black", AnchorString = "/l2e/", AnchorYOffset = "-8", AnchorUnits = "pixels", AnchorXOffset = "105", TabLabel = "l2e", Formula = $"[l2q] * {price2}", RoundDecimalPlaces = "0", Required = "true", Locked = "true", DisableAutoSize = "false", }; FormulaTab formulaTab3 = new FormulaTab { Font = "helvetica", FontSize = "size11", FontColor = "black", AnchorString = "/l3t/", AnchorYOffset = "-8", AnchorUnits = "pixels", AnchorXOffset = "105", TabLabel = "l3t", Formula = "[l1e] + [l2e]", RoundDecimalPlaces = "0", Required = "true", Locked = "true", DisableAutoSize = "false", Bold = "true", }; Tabs tabs = new Tabs { FormulaTabs = new List { formulaTab1, formulaTab2, formulaTab3 }, }; Signer signer = new Signer { Email = signerEmail, Name = signerName, ClientUserId = signerClientId, RecipientId = "1", RoutingOrder = "1", RoleName = "Signer", Tabs = tabs, }; CarbonCopy cc = new CarbonCopy { Email = ccEmail, Name = ccName, RecipientId = "2", RoutingOrder = "1", }; string htmlMarkup = System.IO.File.ReadAllText("order_form.html"); string htmlWithData = htmlMarkup.Replace("{signerName}", signerName) .Replace("{signerEmail}", signerEmail) .Replace("{ccName}", ccName) .Replace("{ccEmail}", ccEmail) .Replace("/sn1/", "") .Replace("/l1q/", " ") .Replace("/l2q/", " "); return new EnvelopeDefinition() { EmailSubject = "Example Signing Document", Documents = new List { new Document { Name = "Lorem Ipsum", DocumentId = "1", HtmlDefinition = new DocumentHtmlDefinition { Source = htmlWithData, }, }, }, Recipients = new Recipients { Signers = new List { signer }, CarbonCopies = new List { cc }, }, Status = "sent", }; } ``` **`Java`** ```java title="Java" private static final String TRUE = "true"; private static final String FALSE = "false"; private static final int L1_PRICE = 5; private static final int L2_PRICE = 150; private static final int ANCHOR_OFFSET_Y = 10; private static final int ANCHOR_OFFSET_X = 20; private static final String DEFAULT_FONT = "helvetica"; private static final String DEFAULT_FONT_SIZE = "size11"; private static final String ANCHOR_UNITS = "pixels"; private static final String HTML_DOCUMENT_FILE_NAME = "templates/order-form.ftl"; public static EnvelopeDefinition makeEnvelope( String signerEmail, String signerName, String signerClientId, String ccEmail, String ccName, WorkArguments args) throws IOException { String htmlDoc = EnvelopeHelpers.createHtmlFromTemplateFile(HTML_DOCUMENT_FILE_NAME, "args", args); htmlDoc = htmlDoc .replace("/l1q/", " ") .replace("/l2q/", " "); ; Signer signer = new Signer() .email(signerEmail) .name(signerName) .clientUserId(signerClientId) .recipientId("1") .routingOrder("1") .roleName("Signer"); CarbonCopy cc = new CarbonCopy() .email(ccEmail) .name(ccName) .recipientId("2") .routingOrder("1"); EnvelopeDefinition envelope = new EnvelopeDefinition(); envelope.setEmailSubject("Example Signing Document"); envelope.setDocuments(Collections.singletonList( new Document() .name("Lorem Ipsum") .documentId("1") .htmlDefinition(new DocumentHtmlDefinition().source(htmlDoc)))); signer.setTabs(createTabs()); envelope.setRecipients(EnvelopeHelpers.createRecipients(signer, cc)); envelope.setStatus(EnvelopeHelpers.ENVELOPE_STATUS_SENT); return envelope; } private static Tabs createTabs() { FormulaTab formulaForFirstNumber = createFormulaTab("/l1e/", "l1e", L1_PRICE, "l1q"); FormulaTab formulaForSecondNumber = createFormulaTab("/l2e/", "l2e", L2_PRICE, "l2q"); FormulaTab finalFormula = new FormulaTab() .font(DEFAULT_FONT) .bold(TRUE) .fontSize(DEFAULT_FONT_SIZE) .anchorString("/l3t/") .anchorYOffset("-8") .anchorUnits(ANCHOR_UNITS) .anchorXOffset("105") .tabLabel("l3t") .formula("[l1e] + [l2e]") .roundDecimalPlaces("0") .required(TRUE) .locked(TRUE) .disableAutoSize(FALSE); Tabs signerTabs = EnvelopeHelpers.createSingleSignerTab("/sn1/", ANCHOR_OFFSET_Y, ANCHOR_OFFSET_X); signerTabs.formulaTabs(Arrays.asList(formulaForFirstNumber, formulaForSecondNumber, finalFormula)); return signerTabs; } private static FormulaTab createFormulaTab(String anchor, String label, int price, String numerical) { return new FormulaTab() .font(DEFAULT_FONT) .fontSize(DEFAULT_FONT_SIZE) .anchorString(anchor) .anchorYOffset("-8") .anchorUnits(ANCHOR_UNITS) .anchorXOffset("105") .tabLabel(label) .formula(String.format("[%s] * {%d}", numerical, price)) .roundDecimalPlaces("0") .required(TRUE) .locked(TRUE) .disableAutoSize(FALSE); } public static ViewUrl responsiveSigning( EnvelopesApi envelopesApi, String accountId, String envelopeId, RecipientViewRequest viewRequest) throws ApiException { var recipientViewResponse = envelopesApi.createRecipientViewWithHttpInfo(accountId, envelopeId, viewRequest); Map> headers = recipientViewResponse.getHeaders(); java.util.List remaining = headers.get("X-RateLimit-Remaining"); java.util.List reset = headers.get("X-RateLimit-Reset"); if (remaining != null & reset != null) { Instant resetInstant = Instant.ofEpochSecond(Long.parseLong(reset.get(0))); System.out.println("API calls remaining: " + remaining); System.out.println("Next Reset: " + resetInstant); } return recipientViewResponse.getData(); } public static RecipientViewRequest makeRecipientViewRequest( String signerEmail, String signerName, DSConfiguration config, String clientUserId) { RecipientViewRequest viewRequest = new RecipientViewRequest(); String stateValue = "?state=123"; viewRequest.setReturnUrl(config.getDsReturnUrl() + stateValue); String authenticationMethod = "none"; viewRequest.setAuthenticationMethod(authenticationMethod); viewRequest.setEmail(signerEmail); viewRequest.setUserName(signerName); viewRequest.setClientUserId(clientUserId); String pingFrequency = "600"; viewRequest.setPingFrequency(pingFrequency); viewRequest.setPingUrl(config.getDsPingUrl()); return viewRequest; } ``` **`Node.js`** ```javascript title="Node.js" function makeEnvelope(args) { let signer = docusign.Signer.constructFromObject({ email: args.signerEmail, name: args.signerName, clientUserId: args.signerClientId, recipientId: '1', routingOrder: '1', roleName: 'Signer', }); // routingOrder (lower means earlier) determines the order of deliveries // to the recipients. Parallel routing order is supported by using the // same integer as the order for two or more recipients. // create a cc recipient to receive a copy of the documents, identified by name and email // We're setting the parameters via setters let cc = new docusign.CarbonCopy.constructFromObject({ email: args.ccEmail, name: args.ccName, routingOrder: '2', recipientId: '2', }); // add formula tabs const price1 = 5; const formulaTab1 = docusign.FormulaTab.constructFromObject({ font: 'helvetica', fontSize: 'size11', fontColor: 'black', anchorString: '/l1e/', anchorYOffset: '-8', anchorUnits: 'pixels', anchorXOffset: '105', tabLabel: 'l1e', formula: `[l1q] * ${price1}`, roundDecimalPlaces: '0', required: 'true', locked: 'true', disableAutoSize: 'false', }); const price2 = 150; const formulaTab2 = docusign.FormulaTab.constructFromObject({ font: 'helvetica', fontSize: 'size11', fontColor: 'black', anchorString: '/l2e/', anchorYOffset: '-8', anchorUnits: 'pixels', anchorXOffset: '105', tabLabel: 'l2e', formula: `[l2q] * ${price2}`, roundDecimalPlaces: '0', required: 'true', locked: 'true', disableAutoSize: 'false', }); const formulaTab3 = docusign.FormulaTab.constructFromObject({ font: 'helvetica', fontSize: 'size11', fontColor: 'black', anchorString: '/l3t/', anchorYOffset: '-8', anchorUnits: 'pixels', anchorXOffset: '105', tabLabel: 'l3t', formula: '[l1e] + [l2e]', roundDecimalPlaces: '0', required: 'true', locked: 'true', disableAutoSize: 'false', bold: 'true', }); const signerTabs = docusign.Tabs.constructFromObject({ formulaTabs: [formulaTab1, formulaTab2, formulaTab3] }); signer.tabs = signerTabs; // Add the recipients to the envelope object let recipients = docusign.Recipients.constructFromObject({ signers: [signer], carbonCopies: [cc], }); // add the document let htmlDefinition = new docusign.DocumentHtmlDefinition(); htmlDefinition.source = getHTMLDocument(args); let document = new docusign.Document(); document.name = 'doc1.html'; // can be different from actual file name document.documentId = '1'; // a label used to reference the doc document.htmlDefinition = htmlDefinition; // create the envelope definition let env = new docusign.EnvelopeDefinition(); env.emailSubject = 'Example Signing Document'; env.documents = [document]; env.recipients = recipients; env.status = args.status; return env; } /** * Gets the HTML document * @function * @private * @param {Object} args parameters for the envelope * @returns {string} A document in HTML format */ function getHTMLDocument(args) { // Data for this method // args.signerEmail // args.signerName // args.ccEmail // args.ccName let docHTMLContent = fs.readFileSync(args.docFile, { encoding: 'utf8' }); // Substitute values into the HTML // Substitute for: {signerName}, {signerEmail}, {ccName}, {ccEmail} return docHTMLContent .replace('{signerName}', args.signerName) .replace('{signerEmail}', args.signerEmail) .replace('{ccName}', args.ccName) .replace('{ccEmail}', args.ccEmail) .replace('/sn1/', '') .replace('/l1q/', '') .replace('/l2q/', ''); } function makeRecipientViewRequest(args) { // Data for this method // args.dsReturnUrl // args.signerEmail // args.signerName // args.signerClientId // args.dsPingUrl let viewRequest = new docusign.RecipientViewRequest(); // Set the url where you want the recipient to go once they are done signing // should typically be a callback route somewhere in your app. // The query parameter is included as an example of how // to save/recover state information during the redirect to // the DocuSign signing. It's usually better to use // the session mechanism of your web framework. Query parameters // can be changed/spoofed very easily. viewRequest.returnUrl = args.dsReturnUrl + '?state=123'; // How has your app authenticated the user? In addition to your app's // authentication, you can include authenticate steps from DocuSign. // Eg, SMS authentication viewRequest.authenticationMethod = 'none'; // Recipient information must match embedded recipient info // we used to create the envelope. viewRequest.email = args.signerEmail; viewRequest.userName = args.signerName; viewRequest.clientUserId = args.signerClientId; // DocuSign recommends that you redirect to DocuSign for the // embedded signing. There are multiple ways to save state. // To maintain your application's session, use the pingUrl // parameter. It causes the DocuSign signing web page // (not the DocuSign server) to send pings via AJAX to your // app, viewRequest.pingFrequency = 600; // seconds // NOTE: The pings will only be sent if the pingUrl is an https address viewRequest.pingUrl = args.dsPingUrl; // optional setting return viewRequest; } ``` **`PHP`** ```php title="PHP" private static function makeEnvelope(array $args, string $demoPath): EnvelopeDefinition { $l1_price = 5; $l2_price = 150; $signer = new Signer( [ 'email' => $args['signer_email'], 'name' => $args['signer_name'], 'recipient_id' => "1", 'routing_order' => "1", 'client_user_id' => $args['signer_client_id'], 'role_name' => 'Signer' ] ); $cc = new CarbonCopy( [ 'email' => $args['cc_email'], 'name' => $args['cc_name'], 'recipient_id' => "2", ] ); $htmlMarkupFileName = 'order_form.html'; $htmlMarkup = file_get_contents($demoPath . $htmlMarkupFileName); $htmlWithData = str_replace( [ '{signer_name}', '{signer_email}', '{cc_name}', '{cc_email}', '/sn1/', '/l1q/', '/l2q/' ], [ $args['signer_name'], $args['signer_email'], $args['cc_name'], $args['cc_email'], '', ' ', '' ], $htmlMarkup ); $formulaForFirstNumber = new FormulaTab([ 'font' => "helvetica", 'font_size' => "size11", 'anchor_string' => '/l1e/', 'anchor_y_offset' => '-8', 'anchor_units' => 'pixels', 'anchor_x_offset' => '105', 'tab_label' => "l1e", 'formula' => "[l1q] * $l1_price", 'round_decimal_places' => "0", 'required' => "true", 'locked' => "true", 'disable_auto_size' => "false", ]); $formulaForSecondNumber = new FormulaTab([ 'font' => "helvetica", 'font_size' => "size11", 'anchor_string' => '/l2e/', 'anchor_y_offset' => '-8', 'anchor_units' => 'pixels', 'anchor_x_offset' => '105', 'tab_label' => "l2e", 'formula' => "[l2q] * $l2_price", 'round_decimal_places' => "0", 'required' => "true", 'locked' => "true", 'disable_auto_size' => "false", ]); $formulaForResult = new FormulaTab([ 'font' => "helvetica", 'bold' => "true", 'font_size' => "size11", 'anchor_string' => '/l3t/', 'anchor_y_offset' => '-8', 'anchor_units' => 'pixels', 'anchor_x_offset' => '105', 'tab_label' => "l3t", 'formula' => '[l1e] + [l2e]', 'round_decimal_places' => "0", 'required' => "true", 'locked' => "true", 'disable_auto_size' => "false", ]); $signer->setTabs(new Tabs([ 'formula_tabs' => [ $formulaForFirstNumber, $formulaForSecondNumber, $formulaForResult, ], ])); return new EnvelopeDefinition( [ 'email_subject' => "Example Signing Document", 'documents' => [ new Document( [ 'name' => 'Lorem Ipsum', # can be different from actual file name 'document_id' => 1, # a label used to reference the doc, 'html_definition' => new DocumentHtmlDefinition( [ 'source' => $htmlWithData ] ) ] ) ], 'recipients' => new Recipients(['signers' => [$signer], 'carbon_copies' => [$cc]]), 'status' => "sent" # requests that the envelope be created and sent. ] ); } ``` **`PowerShell`** ```text title="PowerShell" @{ emailSubject = "Example Signing Document"; documents = @( @{ name = "doc1.html"; documentId = "1"; htmlDefinition = @{ source = "$(Get-Content $doc_html)"; }; }; ); recipients = @{ signers = @( @{ email = $variables.SIGNER_EMAIL; name = $variables.SIGNER_NAME; recipientId = "1"; routingOrder = "1"; clientUserId = "1000"; roleName = "Signer"; tabs = @{ formulaTabs = @( @{ font = "helvetica"; fontSize = "size11"; fontColor = "black"; anchorString = "/l1e/"; anchorYOffset = "-8"; anchorUnits = "pixels"; anchorXOffset = "105"; tabLabel = "l1e"; formula = "[l1q] * $price1"; roundDecimalPlaces = "0"; required = "true"; locked = "true"; disableAutoSize = "false"; }; @{ font = "helvetica"; fontSize = "size11"; fontColor = "black"; anchorString = "/l2e/"; anchorYOffset = "-8"; anchorUnits = "pixels"; anchorXOffset = "105"; tabLabel = "l2e"; formula = "[l2q] * $price2"; roundDecimalPlaces = "0"; required = "true"; locked = "true"; disableAutoSize = "false"; }; @{ font = "helvetica"; fontSize = "size11"; fontColor = "black"; anchorString = "/l3t/"; anchorYOffset = "-8"; anchorUnits = "pixels"; anchorXOffset = "105"; tabLabel = "l3t"; formula = "[l1e] + [l2e]"; roundDecimalPlaces = "0"; required = "true"; locked = "true"; disableAutoSize = "false"; bold = "true"; }; ); }; }; ); carbonCopies = @( @{ email = $variables.CC_EMAIL; name = $variables.CC_NAME; recipientId = "2"; routingOrder = "2"; }; ); }; status = "sent"; } | ConvertTo-Json -Depth 32 > $requestData ``` **`Python`** ```python title="Python" def make_envelope(cls, args): """ Creates envelope args -- parameters for the envelope: signer_email, signer_name, signer_client_id returns an envelope definition """ html_definition = DocumentHtmlDefinition( source=cls.get_html_content(args) ) # Create the document model document = Document( # create the DocuSign document object html_definition=html_definition, name="doc1.html", # can be different from actual file name document_id=1 # a label used to reference the doc ) price_1 = 5 formula_tab_1 = FormulaTab( font="helvetica", font_size="size11", font_color="black", anchor_string="/l1e/", anchor_y_offset="-8", anchor_units="pixels", anchor_x_offset="105", tab_label="l1e", formula=f"[l1q] * {price_1}", round_decimal_places="0", required="true", locked="true", disable_auto_size="false" ) price_2 = 150 formula_tab_2 = FormulaTab( font="helvetica", font_size="size11", font_color="black", anchor_string="/l2e/", anchor_y_offset="-8", anchor_units="pixels", anchor_x_offset="105", tab_label="l2e", formula=f"[l2q] * {price_2}", round_decimal_places="0", required="true", locked="true", disable_auto_size="false" ) formula_tab_3 = FormulaTab( font="helvetica", font_size="size11", font_color="black", anchor_string="/l3t/", anchor_y_offset="-8", anchor_units="pixels", anchor_x_offset="105", tab_label="l3t", formula="[l1e] + [l2e]", round_decimal_places="0", required="true", locked="true", disable_auto_size="false" ) tabs = Tabs( formula_tabs=[formula_tab_1, formula_tab_2, formula_tab_3] ) # Create the signer recipient model signer = Signer( # The signer email=args["signer_email"], name=args["signer_name"], recipient_id="1", routing_order="1", # Setting the client_user_id marks the signer as embedded client_user_id=args["signer_client_id"], role_name="Signer", tabs=tabs ) cc = CarbonCopy( email=args["cc_email"], name=args["cc_name"], recipient_id="2", routing_order="2" ) # Next, create the top level envelope definition and populate it. envelope_definition = EnvelopeDefinition( email_subject="Example Signing Document", documents=[document], # The Recipients object wants arrays for each recipient type recipients=Recipients(signers=[signer], carbon_copies=[cc]), status="sent" # requests that the envelope be created and sent. ) return envelope_definition @classmethod def get_html_content(cls, args): with open(path.join(demo_docs_path, order_form_html_file), "r") as file: doc_html = file.read() return doc_html.replace("{signer_name}", args["signer_name"]) \ .replace("{signer_email}", args["signer_email"]) \ .replace("{cc_name}", args["cc_name"]) \ .replace("{cc_email}", args["cc_email"]) \ .replace("/sn1/", "") \ .replace("/l1q/", "") \ .replace("/l2q/", "") ``` **`Ruby`** ```ruby title="Ruby" def make_envelope(args) envelope_definition = DocuSign_eSign::EnvelopeDefinition.new envelope_definition.email_subject = 'Example Signing Document' html_definition = DocuSign_eSign::DocumentHtmlDefinition.new html_definition.source = get_html_content(args) doc = DocuSign_eSign::Document.new doc.name = 'doc1.html' doc.document_id = '1' doc.html_definition = html_definition # The order in the docs array determines the order in the envelope envelope_definition.documents = [doc] # Create a signer recipient to sign the document, identified by name and email # We're setting the parameters via the object creation price_1 = 5 formula_tab_1 = DocuSign_eSign::FormulaTab.new({ font: 'helvetica', fontSize: 'size11', fontColor: 'black', anchorString: '/l1e/', anchorYOffset: '-8', anchorUnits: 'pixels', anchorXOffset: '105', tabLabel: 'l1e', formula: "[l1q] * #{price_1}", roundDecimalPlaces: '0', required: 'true', locked: 'true', disableAutoSize: 'false' }) price_2 = 150 formula_tab_2 = DocuSign_eSign::FormulaTab.new({ font: 'helvetica', fontSize: 'size11', fontColor: 'black', anchorString: '/l2e/', anchorYOffset: '-8', anchorUnits: 'pixels', anchorXOffset: '105', tabLabel: 'l2e', formula: "[l2q] * #{price_2}", roundDecimalPlaces: '0', required: 'true', locked: 'true', disableAutoSize: 'false' }) formula_tab_3 = DocuSign_eSign::FormulaTab.new({ font: 'helvetica', fontSize: 'size11', fontColor: 'black', anchorString: '/l3t/', anchorYOffset: '-8', anchorUnits: 'pixels', anchorXOffset: '105', tabLabel: 'l3t', formula: '[l1e] + [l2e]', roundDecimalPlaces: '0', required: 'true', locked: 'true', disableAutoSize: 'false' }) tabs = DocuSign_eSign::Tabs.new({ formulaTabs: [formula_tab_1, formula_tab_2, formula_tab_3] }) signer = DocuSign_eSign::Signer.new({ email: args[:signer_email], name: args[:signer_name], clientUserId: args[:signer_client_id], recipientId: 1, role_name: 'Signer', tabs: tabs }) cc = DocuSign_eSign::CarbonCopy.new({ email: args[:cc_email], name: args[:cc_name], recipientId: 2 }) # Add the recipients to the envelope object recipients = DocuSign_eSign::Recipients.new recipients.signers = [signer] recipients.carbon_copies = [cc] envelope_definition.recipients = recipients # Request that the envelope be sent by setting status to "sent". # To request that the envelope be created as a draft, set status to "created" envelope_definition.status = 'sent' envelope_definition end def get_html_content(args) doc_html = File.open(args[:doc_file]).read # Substitute values into the HTML # Substitute for: {signerName}, {signerEmail}, {ccName}, {ccEmail} doc_html.gsub('{signerName}', args[:signer_name]) \ .gsub('{signerEmail}', args[:signer_email]) \ .gsub('{ccName}', args[:cc_name]) \ .gsub('{ccEmail}', args[:cc_email]) \ .gsub('/sn1/', '') \ .gsub('/l1q/', '') \ .gsub('/l2q/', '') end ``` ## Step 3. Call the eSignature REST API Finally, use the definition of the envelope that you created in Step 2 to create a new envelope and send it, adding your access token and base path to the request header. > **Note** > > View the source code for this how-to on GitHub: [Bash](https://github.com/docusign/code-examples-bash/blob/master/examples/eSignature/eg038ResponsiveSigning.sh), [C#](https://github.com/docusign/code-examples-csharp/blob/master/launcher-csharp/eSignature/Examples/ResponsiveSigning.cs), [Java](https://github.com/docusign/code-examples-java/blob/master/src/main/java/com/docusign/controller/eSignature/services/ResponsiveSigningService.java), [Node.js](https://github.com/docusign/code-examples-node/blob/master/lib/eSignature/examples/responsiveSigning.js), [PHP](https://github.com/docusign/code-examples-php/blob/master/src/Services/Examples/eSignature/ResponsiveSigningService.php), [PowerShell](https://github.com/docusign/code-examples-powershell/blob/master/examples/eSignature/eg038ResponsiveSigning.ps1), [Python](https://github.com/docusign/code-examples-python/blob/master/app/eSignature/examples/eg038_responsive_signing.py), or [Ruby](https://github.com/docusign/code-examples-ruby/blob/master/app/services/e_sign/eg038_responsive_signing_service.rb). **`Bash`** ```bash title="Bash" curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \ --header "Content-Type: application/json" \ --data-binary @${request_data} \ --request POST ${base_path}/v2.1/accounts/${account_id}/envelopes \ --output ${response} ``` **`C#`** ```csharp title="C#" EnvelopeDefinition envelope = MakeEnvelope(signerEmail, signerName, ccEmail, ccName, signerClientId); DocuSignClient docuSignClient = new DocuSignClient(basePath); docuSignClient.Configuration.DefaultHeader.Add("Authorization", "Bearer " + accessToken); EnvelopesApi envelopesApi = new EnvelopesApi(docuSignClient); var envelopeSummary = envelopesApi.CreateEnvelopeWithHttpInfo(accountId, envelope); envelopeSummary.Headers.TryGetValue("X-RateLimit-Remaining", out string remaining); envelopeSummary.Headers.TryGetValue("X-RateLimit-Reset", out string reset); if (reset != null && remaining != null) { DateTime resetDate = DateTimeOffset.FromUnixTimeSeconds(long.Parse(reset)).UtcDateTime; Console.WriteLine("API calls remaining: " + remaining); Console.WriteLine("Next Reset: " + resetDate); } ``` **`Java`** ```java title="Java" protected Object doWork(WorkArguments args, ModelMap model, HttpServletResponse response) throws ApiException, IOException { String signerName = args.getSignerName(); String signerEmail = args.getSignerEmail(); String ccName = args.getCcName(); String ccEmail = args.getCcEmail(); String accountId = session.getAccountId(); ViewUrl viewUrl = null; EnvelopeDefinition envelope = ResponsiveSigningService.makeEnvelope( signerEmail, signerName, SIGNER_CLIENT_ID, ccEmail, ccName, args); ApiClient apiClient = createApiClient(session.getBasePath(), user.getAccessToken()); EnvelopesApi envelopesApi = new EnvelopesApi(apiClient); try { var envelopeSummary = envelopesApi.createEnvelopeWithHttpInfo( accountId, envelope, envelopesApi.new CreateEnvelopeOptions()); Map> headers = envelopeSummary.getHeaders(); java.util.List remaining = headers.get("X-RateLimit-Remaining"); List reset = headers.get("X-RateLimit-Reset"); if (remaining != null & reset != null) { Instant resetInstant = Instant.ofEpochSecond(Long.parseLong(reset.get(0))); System.out.println("API calls remaining: " + remaining); System.out.println("Next Reset: " + resetInstant); } String envelopeId = envelopeSummary.getData().getEnvelopeId(); RecipientViewRequest viewRequest = ResponsiveSigningService.makeRecipientViewRequest( signerEmail, signerName, config, SIGNER_CLIENT_ID); viewUrl = ResponsiveSigningService.responsiveSigning( envelopesApi, accountId, envelopeId, viewRequest); } catch (ApiException apiException) { log.error(apiException.getMessage()); DoneExample.createDefault(this.title) .withMessage("Feature Not Enabled") .withFixingInstructions(FEATURE_WAS_DISABLED) .addToModel(model, config); return ERROR_PAGE; } return new RedirectView(viewUrl.getUrl()); } ``` **`Node.js`** ```javascript title="Node.js" let dsApiClient = new docusign.ApiClient(); dsApiClient.setBasePath(args.basePath); dsApiClient.addDefaultHeader('Authorization', 'Bearer ' + args.accessToken); let envelopesApi = new docusign.EnvelopesApi(dsApiClient); // Step 1. Make the envelope body let envelope = makeEnvelope(args.envelopeArgs); // Step 2. Send the envelope let results = await envelopesApi.createEnvelope(args.accountId, { envelopeDefinition: envelope, }, (error, data, response) => { const headers = response?.headers; const remaining = headers?.['x-ratelimit-remaining']; const reset = headers?.['x-ratelimit-reset']; if (remaining && reset) { const resetInstant = new Date(Number(reset) * 1000); console.log(`API calls remaining: ${remaining}`); console.log(`Next Reset: ${resetInstant.toISOString()}`); } }); let envelopeId = results.data.envelopeId; // Step 3. Create the recipient view let viewRequest = makeRecipientViewRequest(args.envelopeArgs); // Call the CreateRecipientView API // Exceptions will be caught by the calling function results = await envelopesApi.createRecipientView(args.accountId, envelopeId, { recipientViewRequest: viewRequest, }, (error, data, response) => { const headers = response?.headers; const remaining = headers?.['x-ratelimit-remaining']; const reset = headers?.['x-ratelimit-reset']; if (remaining && reset) { const resetInstant = new Date(Number(reset) * 1000); console.log(`API calls remaining: ${remaining}`); console.log(`Next Reset: ${resetInstant.toISOString()}`); } }); ``` **`PHP`** ```php title="PHP" public static function worker(array $args, SignatureClientService $clientService, string $demoPath): string { $envelopeDefinition = ResponsiveSigningService::makeEnvelope($args["envelope_args"], $demoPath); $envelopeApi = $clientService->getEnvelopeApi(); try { $envelopeSummary = $envelopeApi->createEnvelopeWithHttpInfo($args['account_id'], $envelopeDefinition); $remaining = $envelopeSummary[2]['X-RateLimit-Remaining'] ?? null; $reset = $envelopeSummary[2]['X-RateLimit-Reset'] ?? null; if ($remaining !== null && $reset !== null) { $resetInstant = (new DateTime())->setTimestamp((int)$reset); error_log("API calls remaining: $remaining"); error_log("Next Reset: " . $resetInstant->format(\DateTime::ATOM)); } } catch (ApiException $e) { $clientService->showErrorTemplate($e); exit; } $envelopeId = $envelopeSummary[0]->getEnvelopeId(); $authenticationMethod = 'None'; $recipientViewRequest = $clientService->getRecipientViewRequest( $authenticationMethod, $args["envelope_args"] ); $viewUrl = $clientService->getRecipientView($args['account_id'], $envelopeId, $recipientViewRequest); return $viewUrl['url']; } ``` **`PowerShell`** ```text title="PowerShell" Invoke-RestMethod ` -Uri "${apiUri}/v2.1/accounts/${accountId}/envelopes" ` -Method 'POST' ` -Headers @{ 'Authorization' = "Bearer $accessToken"; 'Content-Type' = "application/json"; } ` -InFile (Resolve-Path $requestData).Path ` -OutFile $response ``` **`Python`** ```python title="Python" def worker(cls, args): """ 1. Create the envelope request object 2. Send the envelope 3. Create the Recipient View request object 4. Obtain the recipient_view_url for the embedded signing """ envelope_args = args["envelope_args"] # Create the envelope request object envelope_definition = cls.make_envelope(envelope_args) # Call Envelopes::create API method # Exceptions will be caught by the calling function api_client = create_api_client(base_path=args["base_path"], access_token=args["access_token"]) envelope_api = EnvelopesApi(api_client) (results, status, headers) = envelope_api.create_envelope_with_http_info(account_id=args["account_id"], envelope_definition=envelope_definition) remaining = headers.get("X-RateLimit-Remaining") reset = headers.get("X-RateLimit-Reset") if remaining is not None and reset is not None: reset_date = dt.fromtimestamp(int(reset), tz=timezone.utc) print(f"API calls remaining: {remaining}") print(f"Next Reset: {reset_date}") envelope_id = results.envelope_id # Create the Recipient View request object recipient_view_request = RecipientViewRequest( authentication_method=authentication_method, client_user_id=envelope_args["signer_client_id"], recipient_id="1", return_url=envelope_args["ds_return_url"], user_name=envelope_args["signer_name"], email=envelope_args["signer_email"] ) # Obtain the recipient_view_url for the embedded signing # Exceptions will be caught by the calling function (results, status, headers) = envelope_api.create_recipient_view_with_http_info( account_id=args["account_id"], envelope_id=envelope_id, recipient_view_request=recipient_view_request ) remaining = headers.get("X-RateLimit-Remaining") reset = headers.get("X-RateLimit-Reset") if remaining is not None and reset is not None: reset_date = dt.fromtimestamp(int(reset), tz=timezone.utc) print(f"API calls remaining: {remaining}") print(f"Next Reset: {reset_date}") return {"envelope_id": envelope_id, "redirect_url": results.url} ``` **`Ruby`** ```ruby title="Ruby" def worker ds_return_url = "#{args[:ds_ping_url]}/ds_common-return" # Create the envelope definition envelope = make_envelope(args) # Call Docusign to create the envelope envelope_api = create_envelope_api(args) results, _status, headers = envelope_api.create_envelope_with_http_info args[:account_id], envelope remaining = headers['X-RateLimit-Remaining'] reset = headers['X-RateLimit-Reset'] if remaining && reset reset_date = Time.at(reset.to_i).utc puts "API calls remaining: #{remaining}" puts "Next Reset: #{reset_date}" end envelope_id = results.envelope_id # Save for future use within the example launcher # session[:envelope_id] = envelope_id # Create the recipient view for the embedded signing view_request = make_recipient_view_request(args, ds_return_url) # Call the CreateRecipientView API results, _status, headers = envelope_api.create_recipient_view_with_http_info args[:account_id], envelope_id, view_request remaining = headers['X-RateLimit-Remaining'] reset = headers['X-RateLimit-Reset'] if remaining && reset reset_date = Time.at(reset.to_i).utc puts "API calls remaining: #{remaining}" puts "Next Reset: #{reset_date}" end # Step 4. Redirect the user to the embedded signing # Don't use an iframe! # State can be stored/recovered using the framework's session or a # query parameter on the returnUrl (see the makeRecipientViewRequest method) # Redirect to results.url results.url end private def make_recipient_view_request(args, ds_return_url) view_request = DocuSign_eSign::RecipientViewRequest.new # Set the URL where you want the recipient to go once they are done signing # should typically be a callback route somewhere in your app. # The query parameter is included as an example of how # to save/recover state information during the redirect to # the Docusign signing. It's usually better to use # the session mechanism of your web framework. Query parameters # can be changed/spoofed very easily. view_request.return_url = "#{ds_return_url}?state=123" # How has your app authenticated the user? In addition to your app's # authentication, you can include authenticate steps from Docusign; # e.g., SMS authentication view_request.authentication_method = 'none' # Recipient information must match the embedded recipient info # that was used to create the envelope view_request.email = args[:signer_email] view_request.user_name = args[:signer_name] view_request.client_user_id = args[:signer_client_id] # Docusign recommends that you redirect to Docusign for the embedded signing. There are # multiple ways to save state. To maintain your application's session, use the pingUrl # parameter. It causes the Docusign signing web page (not the Docusign server) # to send pings via AJAX to your app view_request.ping_frequency = '600' # seconds # NOTE: The pings will only be sent if the pingUrl is an HTTPS address view_request.ping_url = args[:ds_ping_url] # Optional setting view_request end ``` ## Expected response If you run this code example from our Quickstart or launcher projects, you should see a JSON response similar to the code shown. In addition, the signer receives an email containing a signing link that they can use to open and electronically sign a document using the Docusign mobile app or the Docusign website. After signing is complete, the recipient receives a carbon copy (CC) of the email that includes all of the completed and signed documents. **`Sample response`** ```json title="Sample response" { "envelopeId":"9348a9b2-xxxx-xxxx-xxxx-e2f9a1e28a69", "uri":"/envelopes/9348a9b2-xxxx-xxxx-xxxx-e2f9a1e28a69", "statusDateTime":"2022-04-22T22:19:43.5200000Z", "status":"sent" } ``` ## Next steps * Run this code example from our [Quickstart](/docs/esign-rest-api/quickstart) or launcher projects: [Bash](https://github.com/docusign/code-examples-bash), [C#](https://github.com/docusign/code-examples-csharp), [Java](https://github.com/docusign/code-examples-java), [Node.js](https://github.com/docusign/code-examples-node), [PHP](https://github.com/docusign/code-examples-php), [PowerShell](https://github.com/docusign/code-examples-powershell), [Python](https://github.com/docusign/code-examples-python), or [Ruby](https://github.com/docusign/code-examples-ruby). * Learn [How to request a signature through your app](/docs/esign-rest-api/how-to/request-signature-in-app-embedded). * See [Responsive signing](/docs/esign-rest-api/esign101/concepts/responsive) for details about the feature. * Learn [How to convert a PDF file into a signable HTML document](/docs/esign-rest-api/how-to/converting-pdf) for responsive signing. * See the [API Reference](/docs/esign-rest-api/reference/envelopes/envelopes/create#schema__envelopedefinition_documents_htmldefinition) for the full list of responsive signing request parameters and configurable options. * See [Setting tabs in HTML documents](/docs/esign-rest-api/esign101/concepts/responsive/setting-tabs) for details about adding tabs to HTML documents, including lists of supported elements and syntax.