> 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 set envelope tab values > Describes how to set values in a tab. This topic demonstrates how to set envelope tab values using [embedded signing](/docs/esign-rest-api/esign101/concepts/embedding) and sends an envelope with an editable numerical tab and editable text tabs. > **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. | | \{CLIENT_USER_ID} | A string value that serves as an identifier of an individual signer throughout the signing process. The combination of this value, the signer's name, and the signer's email is used to uniquely identify them. | | Document to be signed | You must provide at least one document to be signed. Document used in this how-to:- [DOCX file](https://github.com/docusign/code-examples-java/blob/master/src/main/resources/World_Wide_Corp_Battle_Plan_Trafalgar.docx) | | \{RECIPIENT_ID} | A unique string value that you assign to identify each recipient. This value assigns tabs on a per-[recipient](/docs/esign-rest-api/esign101/concepts/recipients) basis. | | \{REDIRECT_URI} | A URL to which the user will be forwarded after authentication. The value for this URL must exactly match one of those pre-registered for the [integration key](/platform/configure-app#integration-key) in your Docusign account. See [redirect URI](/platform/configure-app#redirect-uri) for details. | | \{SIGNER_EMAIL} | A string value for the email address where the signer will receive a notification of the signing request. | | \{SIGNER_NAME} | A string value for the full name of the signer. | ## Step 1. Obtain your OAuth token To make the API calls 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. Construct your API headers After you have a valid OAuth access token, you are ready to construct the API headers that you will pass to the API call. Construct your headers like this, but make sure to substitute your valid OAuth access token for \{ACCESS_TOKEN}. **`Bash`** ```bash title="Bash" declare -a Headers=('--header' "Authorization: Bearer ${ACCESS_TOKEN}" '--header' "Accept: application/json" '--header' "Content-Type: application/json") ``` **`C#`** ```csharp title="C#" var docuSignClient = new DocuSignClient(basePath); docuSignClient.Configuration.DefaultHeader.Add("Authorization", "Bearer " + accessToken); ``` **`Java`** ```java title="Java" ApiClient apiClient = createApiClient(session.getBasePath(), user.getAccessToken()); EnvelopesApi envelopesApi = new EnvelopesApi(apiClient); ``` **`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); ``` **`PHP`** ```php title="PHP" $config = new Configuration(); $config->setHost($args['base_path']); $config->addDefaultHeader('Authorization', 'Bearer ' . $args['ds_access_token']); $this->apiClient = new ApiClient($config); ``` **`PowerShell`** ```text title="PowerShell" $headers = @{ 'Authorization' = "Bearer $accessToken"; 'Content-Type' = "application/json"; } ``` **`Python`** ```python title="Python" api_client = create_api_client( base_path=args["base_path"], access_token=args["access_token"] ) ``` **`Ruby`** ```ruby title="Ruby" configuration = DocuSign_eSign::Configuration.new configuration.host = args[:base_path] api_client = DocuSign_eSign::ApiClient.new configuration api_client.default_headers['Authorization'] = "Bearer #{args[:access_token]}" ``` ## Step 3. Construct the request body If you're using a Docusign SDK, you can prepare a compatible request body by creating an envelope definition using the included `makeEnvelope` method. * Set a `signHere` tab to collect signature information. * Create two text tabs to collect a full name and a familiar name of the signer to prefill the document. * Create a numerical tab for salary. * Set the associated anchor strings so they match their placement within the document and include a tab ID so they are easy to [retrieve](/docs/esign-rest-api/how-to/get-envelope-tab-values). **`Bash`** ```bash title="Bash" printf \ '{ "customFields": { "textCustomFields": [{ "name": "salary", "required": "false", "show": "true", "value": "123000" }] }, "documents": [ { "documentBase64": "' > $request_data cat $doc1_base64 >> $request_data printf '", "documentId": "1", "fileExtension": "docx", "name": "Lorem Ipsum" } ], "emailBlurb": "Sample text for email body", "emailSubject": "Please Sign", "envelopeIdStamping": "true", "recipients": { "signers": [{ "clientUserId": "1000", "email": "'"${SIGNER_EMAIL}"'", "name": "'"${SIGNER_NAME}"'", "recipientId": "1", "routingOrder": "1", "tabs": { "signHereTabs": [{ "anchorString": "/sn1/", "anchorUnits": "pixels", "anchorXOffset": "20", "anchorYOffset": "10" }], "textTabs": [{ "anchorString": "/legal/", "anchorUnits": "pixels", "anchorXOffset": "5", "anchorYOffset": "-9", "bold": "true", "font": "helvetica", "fontSize": "size11", "locked": "false", "tabId": "legal_name", "tabLabel": "Legal name", "value": "'"${SIGNER_NAME}"'" }, { "anchorString": "/familiar/", "anchorUnits": "pixels", "anchorXOffset": "5", "anchorYOffset": "-9", "bold": "true", "font": "helvetica", "fontSize": "size11", "locked": "false", "tabId": "familiar_name", "tabLabel": "Familiar name", "value": "'"${SIGNER_NAME}"'" }], "numericalTabs" : [ { "pageNumber" : "1", "documentID" : "1", "xPosition" : "210", "yPosition" : "235", "height" : "20", "width" : "70", "minNumericalValue" : "0", "maxNumericalValue" : "1000000", "validationType" : "Currency", "bold": "true", "font": "helvetica", "fontSize": "size11", "tabId": "salary", "tabLabel": "Salary", "numericalValue": "123000", "localePolicy" : { "cultureName" : "en-US", "currencyCode": "usd", "currencyPositiveFormat" : "csym_1_comma_234_comma_567_period_89", "currencyNegativeFormat" : "minus_csym_1_comma_234_comma_567_period_89", "useLongCurrencyFormat" : "true" } }] } }] }, "status": "Sent" }' >> $request_data ``` **`C#`** ```csharp title="C#" // Create Tabs and CustomFields SignHere signHere = new SignHere { AnchorString = "/sn1/", AnchorUnits = "pixels", AnchorYOffset = "10", AnchorXOffset = "20", }; Text textLegal = new Text { AnchorString = "/legal/", AnchorUnits = "pixels", AnchorYOffset = "-9", AnchorXOffset = "5", Font = "helvetica", FontSize = "size11", Bold = "true", Value = signerName, Locked = "false", TabId = "legal_name", TabLabel = "Legal name", }; Text textFamiliar = new Text { AnchorString = "/familiar/", AnchorUnits = "pixels", AnchorYOffset = "-9", AnchorXOffset = "5", Font = "helvetica", FontSize = "size11", Bold = "true", Value = signerName, Locked = "false", TabId = "familiar_name", TabLabel = "Familiar name", }; // The salary is set both as a readable number in the /salary/ text field, // and as a pure number in a custom field ('salary') in the envelope int salary = 123000; Numerical numericalSalary = new Numerical { ValidationType = "Currency", XPosition = "210", YPosition = "235", Height = "20", Width = "70", PageNumber = "1", DocumentId = "1", MinNumericalValue = "0", MaxNumericalValue = "1000000", TabId = "salary", TabLabel = "Salary", NumericalValue = salary.ToString(), LocalePolicy = new LocalePolicyTab { CultureName = "en-US", CurrencyCode = "usd", CurrencyPositiveFormat = "csym_1_comma_234_comma_567_period_89", CurrencyNegativeFormat = "minus_csym_1_comma_234_comma_567_period_89", UseLongCurrencyFormat = "true", }, }; TextCustomField salaryCustomField = new TextCustomField { Name = "salary", Required = "false", Show = "true", // Yes, include in the CoC Value = salary.ToString(), }; CustomFields cf = new CustomFields { TextCustomFields = new List { salaryCustomField }, }; // Create a signer recipient to sign the document, identified by name and email // We're setting the parameters via the object creation Signer signer1 = new Signer { Email = signerEmail, Name = signerName, RecipientId = "1", RoutingOrder = "1", ClientUserId = signerClientId, }; // Add the tabs model (including the SignHere tab) to the signer. // The Tabs object wants arrays of the different field/tab types // Tabs are set per recipient/signer Tabs signer1Tabs = new Tabs { SignHereTabs = new List { signHere }, TextTabs = new List { textLegal, textFamiliar }, NumericalTabs = new List { numericalSalary }, }; signer1.Tabs = signer1Tabs; Recipients recipients = new Recipients { Signers = new List { signer1 }, }; string doc1B64 = Convert.ToBase64String(System.IO.File.ReadAllBytes(docDocx)); // Create document objects, one per document Document doc1 = new Document { DocumentBase64 = doc1B64, Name = "Lorem Ipsum", // Can be different from actual file name FileExtension = "docx", DocumentId = "1", }; // Create the envelope definition EnvelopeDefinition envelopeAttributes = new EnvelopeDefinition() { EnvelopeIdStamping = "true", EmailSubject = "Please Sign", EmailBlurb = "Sample text for email body", Status = "Sent", Recipients = recipients, CustomFields = cf, Documents = new List { doc1 }, }; ``` **`Java`** ```java title="Java" public static EnvelopeDefinition makeEnvelope(String signerEmail, String signerName) throws IOException { // Create a signer recipient to sign the document, identified by name and email // We set the clientUserId to enable embedded signing for the recipient Signer signer = new Signer(); signer.setEmail(signerEmail); signer.setName(signerName); signer.clientUserId(SIGNER_CLIENT_ID); signer.recipientId("1"); // Create tabs and CustomFields SignHere signHere = new SignHere(); signHere.setAnchorString("/sn1"); signHere.setAnchorUnits("pixels"); signHere.setAnchorYOffset("10"); signHere.setAnchorXOffset("20"); Text textLegal = new Text(); textLegal.setAnchorString("/legal/"); textLegal.setAnchorUnits("pixels"); textLegal.setAnchorYOffset("-9"); textLegal.setAnchorXOffset("5"); textLegal.setFont("helvetica"); textLegal.setFontSize("size11"); textLegal.setBold("true"); textLegal.setValue(signerName); textLegal.setLocked("false"); textLegal.setTabId("legal_name"); textLegal.setTabLabel("Legal Name"); Text textFamiliar = new Text(); textFamiliar.setAnchorString("/familiar/"); textFamiliar.setAnchorUnits("pixels"); textFamiliar.setAnchorYOffset("-9"); textFamiliar.setAnchorXOffset("5"); textFamiliar.setFont("helvetica"); textFamiliar.setFontSize("size11"); textFamiliar.setBold("true"); textFamiliar.setValue(signerName); textFamiliar.setLocked("false"); textFamiliar.setTabId("familiar_name"); textFamiliar.setTabLabel("Familiar Name"); Integer salary = 123000; Numerical numericalSalary = new Numerical(); numericalSalary.setValidationType("Currency"); numericalSalary.setPageNumber("1"); numericalSalary.setDocumentId("1"); numericalSalary.setXPosition("210"); numericalSalary.setYPosition("235"); numericalSalary.setHeight("20"); numericalSalary.setWidth("70"); numericalSalary.setFont("helvetica"); numericalSalary.setFontSize("size11"); numericalSalary.setBold("true"); numericalSalary.setNumericalValue(String.format("%d", salary)); numericalSalary.setTabId("salary"); numericalSalary.setTabLabel("salary"); LocalePolicyTab localePolicyTab = new LocalePolicyTab(); localePolicyTab.setCultureName("en-US"); localePolicyTab.setCurrencyCode("usd"); localePolicyTab.setCurrencyPositiveFormat("csym_1_comma_234_comma_567_period_89"); localePolicyTab.setCurrencyNegativeFormat("minus_csym_1_comma_234_comma_567_period_89"); localePolicyTab.setUseLongCurrencyFormat("true"); numericalSalary.setLocalePolicy(localePolicyTab); TextCustomField salaryCustomField = new TextCustomField(); salaryCustomField.setName("salary"); salaryCustomField.setRequired("false"); salaryCustomField.setShow("true"); // Yes, included in the CoC salaryCustomField.setValue(String.valueOf(salary)); CustomFields cf = new CustomFields(); cf.setTextCustomFields(Collections.singletonList(salaryCustomField)); Tabs tabs = new Tabs(); tabs.setSignHereTabs(Collections.singletonList(signHere)); tabs.setTextTabs(Arrays.asList(textLegal, textFamiliar)); tabs.setNumericalTabs(List.of(numericalSalary)); signer.setTabs(tabs); // Add the recipient to the envelope object Recipients recipients = new Recipients(); recipients.setSigners(Collections.singletonList(signer)); EnvelopeDefinition envelopeDefinition = new EnvelopeDefinition(); envelopeDefinition.setEmailSubject("Please sign this document from the Java SDK"); envelopeDefinition.setRecipients(recipients); Document doc = EnvelopeHelpers.createDocumentFromFile(DOCUMENT_FILE_NAME, DOCUMENT_NAME, "1"); envelopeDefinition.setDocuments(Collections.singletonList(doc)); envelopeDefinition.setCustomFields(cf); // Request that the envelope be sent by setting |status| to "sent". // To request that the envelope be created as a draft, set to "created" envelopeDefinition.setStatus(EnvelopeHelpers.ENVELOPE_STATUS_SENT); return envelopeDefinition; } ``` **`Node.js`** ```javascript title="Node.js" let envelope = makeEnvelope(envelopeArgs); function makeEnvelope(args) { // Data for this method // args.signerEmail // args.signerName // args.signerClientId // document 1 (docx) has tags // /sn1/ - signature field // /salary/ - yearly salary // /legal/ - legal name // /familiar/ - person's familiar name // // The envelope has one recipient. // recipient 1 - signer // // The salary is set both as a readable number in the // /salary/ text field, and as a pure number in a // custom field ('salary') in the envelope. // Salary that will be used. // read file from a local directory // The read could raise an exception if the file is not available! let docBytes = fs.readFileSync(args.docFile); let doc1b64 = Buffer.from(docBytes).toString('base64'); // create the document model let document = docusign.Document.constructFromObject({ documentBase64: doc1b64, name: 'Lorem Ipsum', // can be different from actual file name fileExtension: 'docx', documentId: '1', }); // Create a signer recipient to sign the document, identified by name and email // We set the clientUserId to enable embedded signing for the recipient let signer = docusign.Signer.constructFromObject({ email: args.signerEmail, name: args.signerName, clientUserId: args.signerClientId, recipientId: 1, }); // Create signHere field (also known as tabs) on the document, let signHere = docusign.SignHere.constructFromObject({ anchorString: '/sn1/', anchorUnits: 'pixels', anchorYOffset: '10', anchorXOffset: '20', }); // Create the legal and familiar text fields. // Recipients can update these values if they wish to. let textLegal = docusign.Text.constructFromObject({ anchorString: '/legal/', anchorUnits: 'pixels', anchorYOffset: '-9', anchorXOffset: '5', font: 'helvetica', fontSize: 'size11', bold: 'true', value: args.signerName, locked: 'false', tabId: 'legal_name', tabLabel: 'Legal name', }); let textFamiliar = docusign.Text.constructFromObject({ anchorString: '/familiar/', anchorUnits: 'pixels', anchorYOffset: '-9', anchorXOffset: '5', font: 'helvetica', fontSize: 'size11', bold: 'true', value: args.signerName, locked: 'false', tabId: 'familiar_name', tabLabel: 'Familiar name', }); // Create the salary field. It should be human readable, so // add a comma before the thousands number, a currency indicator, etc. localePolicyTab = docusign.LocalePolicyTab.constructFromObject({ cultureName: 'en-US', currencyCode: 'usd', currencyPositiveFormat: 'csym_1_comma_234_comma_567_period_89', currencyNegativeFormat: 'minus_csym_1_comma_234_comma_567_period_89', useLongCurrencyFormat: 'true' }); numericalSalary = docusign.Numerical.constructFromObject({ pageNumber: '1', documentId: '1', xPosition: '210', yPosition: '235', height: '20', width: '70', font: 'helvetica', fontSize: 'size11', bold: 'true', tabId: 'salary', tabLabel: 'Salary', validationType: 'Currency', numericalValue: '123000', localePolicy: localePolicyTab }); // Add the tabs model (including the sign_here tab) to the signer. // The Tabs object wants arrays of the different field/tab types signer.tabs = docusign.Tabs.constructFromObject({ signHereTabs: [signHere], textTabs: [textLegal, textFamiliar], numericalTabs: [numericalSalary], }); // Create an envelope custom field to save the "real" (numeric) // version of the salary salaryCustomField = docusign.TextCustomField.constructFromObject({ name: 'salary', required: 'false', show: 'true', // Yes, include in the CoC value: '123000', }); customFields = docusign.CustomFields.constructFromObject({ textCustomFields: [salaryCustomField], }); // Next, create the top level envelope definition and populate it. envelopeDefinition = docusign.EnvelopeDefinition.constructFromObject({ emailSubject: 'Please sign this salary document', documents: [document], // The Recipients object wants arrays for each recipient type recipients: docusign.Recipients.constructFromObject({ signers: [signer] }), status: 'sent', // requests that the envelope be created and sent. customFields: customFields, }); return envelopeDefinition; } ``` **`PHP`** ```php title="PHP" public static function makeEnvelope(array $args, $demoDocsPath): EnvelopeDefinition { # document 1 (pdf) has tags # /sn1/ - signature field # /salary/ - yearly salary # /legal/ - legal name # /familiar/ - person's familiar name # # The envelope has one recipient. # recipient 1 - signer # # The salary is set both as a readable number in the # /salary/ text field, and as a pure number in a # custom field ('salary') in the envelope. # Read the file $doc_name = 'World_Wide_Corp_salary.docx'; $content_bytes = file_get_contents($demoDocsPath . $doc_name); $base64_file_content = base64_encode($content_bytes); # Create the document model $document = new Document([ # create the DocuSign document object 'document_base64' => $base64_file_content, 'name' => 'Salary action', # can be different from actual file name 'file_extension' => 'docx', # many different document types are accepted 'document_id' => 1 # a label used to reference the doc ]); # Create the signer recipient model $signer = new 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'] ]); # Create a sign_here tab (field on the document) $sign_here = new SignHere([ # DocuSign SignHere field/tab 'anchor_string' => '/sn1/', 'anchor_units' => 'pixels', 'anchor_y_offset' => '10', 'anchor_x_offset' => '20' ]); # Create the legal and familiar text fields. # Recipients can update these values if they wish to. $text_legal = new Text([ 'anchor_string' => '/legal/', 'anchor_units' => 'pixels', 'anchor_x_offset' => '5', 'anchor_y_offset' => '-6', 'font' => "helvetica", 'font_size' => "size11", 'bold' => 'true', 'value' => $args['signer_name'], 'locked' => 'false', 'tab_id' => 'legal_name', 'tab_label' => 'Legal name']); $text_familiar = new Text([ 'anchor_string' => '/familiar/', 'anchor_units' => 'pixels', 'anchor_y_offset' => '-6', 'anchor_x_offset' => '5', 'font' => "helvetica", 'font_size' => "size11", 'bold' => 'true', 'value' => $args['signer_name'], 'locked' => 'false', 'tab_id' => 'familiar_name', 'tab_label' => 'Familiar name']); # Create the salary field. It should be human readable, so # add a comma before the thousands number, a currency indicator, etc. $salary = 123000; $locale_policy_tab = new LocalePolicyTab([ "culture_name" => "en-US", "currency_code" => "usd", "currency_positive_format" => "csym_1_comma_234_comma_567_period_89", "currency_negative_format" => "minus_csym_1_comma_234_comma_567_period_89", "use_long_currency_format" => "true" ]); $numerical_salary = new Numerical([ 'page_number' => '1', 'document_id' => '1', 'x_position' => '210', 'y_position' => '233', 'height' => "20", 'width' => "70", 'min_numerical_value' => "0", 'max_numerical_value' => "1000000", 'validation_type' => 'Currency', 'font' => "helvetica", 'font_size' => "size11", 'bold' => 'true', 'tab_id' => 'salary', 'tab_label' => 'Salary', 'numerical_value' => strval($salary), 'locale_policy' => $locale_policy_tab ]); # Add the tabs model (including the sign_here tab) to the signer # The Tabs object wants arrays of the different field/tab types $signer->settabs(new Tabs( ['sign_here_tabs' => [$sign_here], 'text_tabs' => [$text_legal, $text_familiar], 'numerical_tabs'=>[$numerical_salary]] )); # Create an envelope custom field to save the "real" (numeric) # version of the salary $salary_custom_field = new TextCustomField([ 'name' => 'salary', 'required' => 'false', 'show' => 'true', # Yes, include in the CoC 'value' => strval($salary)]); $custom_fields = new CustomFields([ 'text_custom_fields' => [$salary_custom_field]]); # Next, create the top level envelope definition and populate it. return new EnvelopeDefinition([ 'email_subject' => "Please sign this document sent from the PHP SDK", 'documents' => [$document], # The Recipients object wants arrays for each recipient type 'recipients' => new Recipients(['signers' => [$signer]]), 'status' => "sent", # requests that the envelope be created and sent. 'custom_fields' => $custom_fields ]); } ``` **`PowerShell`** ```text title="PowerShell" @{ customFields = @{ textCustomFields = @(@{ name = "salary"; required = "false"; show = "true"; value = "123000"; }; ); }; documents = @( @{ documentBase64 = "$(Get-Content $doc1Base64)"; documentId = "1"; fileExtension = "docx"; name = "Lorem Ipsum"; }; ); emailBlurb = "Sample text for email body"; emailSubject = "Please Sign"; envelopeIdStamping = "true"; recipients = @{ signers = @(@{ clientUserId = "1000"; email = $variables.SIGNER_EMAIL; name = $variables.SIGNER_NAME; recipientId = "1"; routingOrder = "1"; tabs = @{ signHereTabs = @(@{ anchorString = "/sn1/"; anchorUnits = "pixels"; anchorXOffset = "20"; anchorYOffset = "10"; }; ); numericalTabs = @(@{ ValidationType = "Currency"; XPosition = "210"; YPosition = "235"; Height = "20"; Width = "70"; PageNumber = "1"; DocumentId = "1"; MinNumericalValue = "0"; MaxNumericalValue = "1000000"; TabId = "salary"; TabLabel = "Salary"; NumericalValue = "123000"; LocalPolicy = @{ CultureName = "en-US"; CurrencyCode = "usd"; CurrencyPositiveFormat = "csym_1_comma_234_comma_567_period_89"; CurrencyNegativeFormat = "minus_csym_1_comma_234_comma_567_period_89"; UseLongCurrencyFormat = "true"; }; }; ); textTabs = @(@{ anchorString = "/legal/"; anchorUnits = "pixels"; anchorXOffset = "5"; anchorYOffset = "-9"; bold = "true"; font = "helvetica"; fontSize = "size11"; locked = "false"; tabId = "legal_name"; tabLabel = "Legal name"; value = $variables.SIGNER_NAME; }; @{ anchorString = "/familiar/"; anchorUnits = "pixels"; anchorXOffset = "5"; anchorYOffset = "-9"; bold = "true"; font = "helvetica"; fontSize = "size11"; locked = "false"; tabId = "familiar_name"; tabLabel = "Familiar name"; value = $variables.SIGNER_NAME; };); }; }; ); }; 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 """ # Document 1 (PDF) has tag /sn1/ # # The envelope has one recipient: # recipient 1 - signer with open(args["doc_file"], "rb") as file: content_bytes = file.read() base64_file_content = base64.b64encode(content_bytes).decode("ascii") # Create the document model document = Document( # Create the DocuSign document object document_base64=base64_file_content, name="Lorem Ipsum", # Can be different from the actual filename file_extension="docx", # Many different document types are accepted document_id=1 # A label used to reference the doc ) # 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"] ) # Create a SignHere tab (field on the document) sign_here = SignHere( # DocuSign SignHere field/tab anchor_string="/sn1/", anchor_units="pixels", anchor_y_offset="10", anchor_x_offset="20" ) text_legal = Text( anchor_string="/legal/", anchor_units="pixels", anchor_y_offset="-9", anchor_x_offset="5", font="helvetica", font_size="size11", bold="true", value=args["signer_name"], locked="false", tab_id="legal_name", tab_label="Legal name") text_familar = Text( anchor_string="/familiar/", anchor_units="pixels", anchor_y_offset="-9", anchor_x_offset="5", font="helvetica", font_size="size11", bold="true", value=args["signer_name"], locked="false", tab_id="familar_name", tab_label="Familiar name") locale_policy_tab = LocalePolicyTab( culture_name="en-US", currency_code="usd", currency_positive_format="csym_1_comma_234_comma_567_period_89", currency_negative_format="minus_csym_1_comma_234_comma_567_period_89", use_long_currency_format="true" ) numerical_salary = Numerical( page_number="1", document_id="1", x_position="210", y_position="235", validation_type="Currency", font="helvetica", font_size="size11", bold="true", locked="false", height="23", tab_id="salary", tab_label="Salary", numerical_value="123000", locale_policy=locale_policy_tab ) salary_custom_field = TextCustomField( name="salary", required="false", show="true", # Yes, include in the CoC value=str(123000) ) cf = CustomFields(text_custom_fields=[salary_custom_field]) # Add the tabs model (including the SignHere tab) to the signer # The Tabs object wants arrays of the different field/tab types signer.tabs = Tabs(sign_here_tabs=[sign_here], text_tabs=[text_legal, text_familar], numerical_tabs=[numerical_salary]) # Create the top level envelope definition and populate it envelope_definition = EnvelopeDefinition( email_subject="Please sign this document sent from the Python SDK", documents=[document], # The Recipients object wants arrays for each recipient type recipients=Recipients(signers=[signer]), custom_fields=cf, status="sent" # Requests that the envelope be created and sent ) return envelope_definition ``` **`Ruby`** ```ruby title="Ruby" def make_envelope(signer_email, signer_name, signer_client_id, pdf_filename) envelope_definition = DocuSign_eSign::EnvelopeDefinition.new envelope_definition.email_subject = 'Please sign this document sent from Ruby SDK' doc1 = DocuSign_eSign::Document.new doc1.document_base64 = Base64.encode64(File.binread(File.join('data', pdf_filename))) doc1.name = 'Lorem Ipsum' doc1.file_extension = 'docx' doc1.document_id = '1' # The order in the docs array determines the order in the envelope envelope_definition.documents = [doc1] # Create a signer recipient to sign the document, identified by name and email # We're setting the parameters via the object creation signer1 = DocuSign_eSign::Signer.new({ email: signer_email, name: signer_name, clientUserId: signer_client_id, recipientId: 1 }) # Create Tabs and CustomFields sign_here1 = DocuSign_eSign::SignHere.new sign_here1.anchor_string = '/sn1/' sign_here1.anchor_units = 'pixels' sign_here1.anchor_x_offset = '20' sign_here1.anchor_y_offset = '10' text_legal = DocuSign_eSign::Text.new text_legal.anchor_string = '/legal/' text_legal.anchor_units = 'pixels' text_legal.anchor_y_offset = '-9' text_legal.anchor_x_offset = '5' text_legal.font = 'Helvetica' text_legal.font_size = 'size11' text_legal.bold = 'true' text_legal.value = signer_name text_legal.locked = 'false' text_legal.tab_id = 'legal_name' text_legal.tab_label = 'Legal name' text_familiar = DocuSign_eSign::Text.new text_familiar.anchor_string = '/familiar/' text_familiar.anchor_units = 'pixels' text_familiar.anchor_y_offset = '-9' text_familiar.anchor_x_offset = '5' text_familiar.font = 'Helvetica' text_familiar.font_size = 'size11' text_familiar.bold = 'true' text_familiar.value = signer_name text_familiar.locked = 'false' text_familiar.tab_id = 'familiar_name' text_familiar.tab_label = 'Familiar name' locale_policy_tab = DocuSign_eSign::LocalePolicyTab.new locale_policy_tab.culture_name = 'en-US' locale_policy_tab.currency_code = 'usd' locale_policy_tab.currency_positive_format = 'csym_1_comma_234_comma_567_period_89' locale_policy_tab.currency_negative_format = 'minus_csym_1_comma_234_comma_567_period_89' locale_policy_tab.use_long_currency_format = 'true' numerical_salary = DocuSign_eSign::Numerical.new numerical_salary.page_number = '1' numerical_salary.document_id = '1' numerical_salary.x_position = '210' numerical_salary.y_position = '235' numerical_salary.height = '20' numerical_salary.width = '70' numerical_salary.min_numerical_value = '0' numerical_salary.max_numerical_value = '1000000' numerical_salary.validation_type = 'Currency' numerical_salary.font = 'Helvetica' numerical_salary.font_size = 'size11' numerical_salary.bold = 'true' numerical_salary.tab_id = 'salary' numerical_salary.tab_label = 'Salary' numerical_salary.numerical_value = '123000' numerical_salary.locale_policy = locale_policy_tab salary_custom_field = DocuSign_eSign::TextCustomField.new salary_custom_field.name = 'salary' salary_custom_field.required = 'false' salary_custom_field.show = 'true' salary_custom_field.value = '123000' cf = DocuSign_eSign::CustomFields.new cf.text_custom_fields = [salary_custom_field] envelope_definition.custom_fields = cf # Tabs are set per recipient / signer tabs = DocuSign_eSign::Tabs.new tabs.sign_here_tabs = [sign_here1] tabs.text_tabs = [text_legal, text_familiar] tabs.numerical_tabs = [numerical_salary] signer1.tabs = tabs # Add the recipients to the envelope object recipients = DocuSign_eSign::Recipients.new recipients.signers = [signer1] 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 ``` ## Step 4. Call the eSignature REST API Now that you have constructed your API headers, make a request to [Envelopes:create](/docs/esign-rest-api/reference/envelopes/envelopes/create) to send an envelope. Here’s how you make the call, but make sure to substitute your valid API account ID for \{account_id}. **`Bash`** ```bash title="Bash" Status=$(curl --request POST ${base_path}/v2.1/accounts/${account_id}/envelopes \ "${Headers[@]}" \ --data-binary @${request_data} \ --output ${response}) ``` **`C#`** ```csharp title="C#" EnvelopesApi envelopesApi = new EnvelopesApi(docuSignClient); var results = envelopesApi.CreateEnvelopeWithHttpInfo(accountId, envelopeAttributes); results.Headers.TryGetValue("X-RateLimit-Remaining", out string remaining); results.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); } string envelopeId = results.Data.EnvelopeId; ``` **`Java`** ```java title="Java" EnvelopeSummary envelopeSummary = SetTabValuesService.createEnvelope(envelopesApi, accountId, envelope); ``` **`Node.js`** ```javascript title="Node.js" 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; ``` **`PHP`** ```php title="PHP" $envelope_api = $clientService->getEnvelopeApi(); $envelopeResponse = $envelope_api->createEnvelopeWithHttpInfo($args['account_id'], $envelope_definition); $remaining = $envelopeResponse[2]['X-RateLimit-Remaining'] ?? null; $reset = $envelopeResponse[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)); } $envelope_id = $envelopeResponse[0]->getEnvelopeId(); ``` **`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" envelopes_api = EnvelopesApi(api_client) (results, status, headers) = envelopes_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 ``` **`Ruby`** ```ruby title="Ruby" results, _status, headers = create_envelope_api(args).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 ``` ## Step 5. Create the recipient view definition The recipient view is the screen that Docusign generates and displays in your app to enable your signers to sign documents. The recipient view request returns a link that enables your recipients to sign documents from your app. To create the definition, you must add the signer's information and the redirect URI. 1. Set the redirect URI to which the user will be forwarded after signing is complete. This URI must exactly match one that is preregistered for the integration key in your Docusign account. **Note**: You can include a `state` parameter in the URI string to record your application's state and provide recovery information, potentially enabling it to resume interrupted operations using only callback data. 2. Add the recipient information to the view, including the signer's email, name, and client user ID. > **Note** > > View the source code for this how-to on GitHub: [Bash](https://github.com/docusign/code-examples-bash/blob/master/examples/eSignature/eg016SetTabValues.sh), [C#](https://github.com/docusign/code-examples-csharp/blob/master/launcher-csharp/eSignature/Examples/SetEnvelopeTabValue.cs), [Java](https://github.com/docusign/code-examples-java/blob/master/src/main/java/com/docusign/controller/eSignature/examples/EG016ControllerSetTabValues.java), [Node.js](https://github.com/docusign/code-examples-node/blob/master/lib/eSignature/examples/setTabValues.js), [PHP](https://github.com/docusign/code-examples-php/blob/master/src/Services/Examples/eSignature/SetTabValuesService.php), [PowerShell](https://github.com/docusign/code-examples-powershell/blob/master/examples/eSignature/eg016SetTabValues.ps1), [Python](https://github.com/docusign/code-examples-python/blob/master/app/eSignature/examples/eg016_set_tab_values.py), or [Ruby](https://github.com/docusign/code-examples-ruby/blob/main/app/services/e_sign/eg016_set_envelope_tab_data_service.rb). **`Bash`** ```bash title="Bash" curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \ --header "Content-Type: application/json" \ --data-binary ' { "returnUrl": "http://httpbin.org/get", "authenticationMethod": "none", "email": "'"${SIGNER_EMAIL}"'", "userName": "'"${SIGNER_NAME}"'", "clientUserId": 1000, }' \ --request POST ${base_path}/v2.1/accounts/${account_id}/envelopes/${envelope_id}/views/recipient \ --output ${response} ``` **`C#`** ```csharp title="C#" RecipientViewRequest viewRequest = new RecipientViewRequest(); // Set the URL where you want the recipient to go once they are done signing; // this 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 ceremony. It's usually better to use // the session mechanism of your web framework. Query parameters // can be changed/spoofed very easily viewRequest.ReturnUrl = returnUrl + "?state=123"; // How has your app authenticated the user? In addition to your app's authentication, // you can include authentication steps from DocuSign; e.g., SMS authentication viewRequest.AuthenticationMethod = "none"; // Recipient information must match the embedded recipient info // that we used to create the envelope viewRequest.Email = signerEmail; viewRequest.UserName = signerName; viewRequest.ClientUserId = signerClientId; // DocuSign recommends that you redirect to DocuSign for the // signing ceremony. There are multiple ways to save state. // To maintain your application's session, use the PingUrl // parameter. It causes the DocuSign Signing Ceremony 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 = pingUrl; // Optional setting var viewUrl = envelopesApi.CreateRecipientViewWithHttpInfo(accountId, results.Data.EnvelopeId, viewRequest); viewUrl.Headers.TryGetValue("X-RateLimit-Remaining", out remaining); viewUrl.Headers.TryGetValue("X-RateLimit-Reset", out 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" RecipientViewRequest viewRequest = SetTabValuesService.makeRecipientViewRequest( signerEmail, signerName, config.getDsReturnUrl(), config.getDsPingUrl()); ViewUrl viewUrl = SetTabValuesService.createRecipientView(envelopesApi, accountId, envelopeId, viewRequest); ``` **`Node.js`** ```javascript title="Node.js" let viewRequest = docusign.RecipientViewRequest.constructFromObject({ returnUrl: envelopeArgs.dsReturnUrl, authenticationMethod: 'none', email: envelopeArgs.signerEmail, userName: envelopeArgs.signerName, clientUserId: envelopeArgs.signerClientId, }); // Step 4. 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" $authentication_method = 'None'; # How is this application authenticating # the signer? See the `authentication_method' definition # https://developers.docusign.com/esign-rest-api/reference/Envelopes/EnvelopeViews/createRecipient $recipient_view_request = $clientService->getRecipientViewRequest( $authentication_method, $args["envelope_args"] ); # Obtain the recipient_view_url for the embedded signing # Exceptions will be caught by the calling function $recipientView = $clientService->getRecipientView($args['account_id'], $envelope_id, $recipient_view_request); ``` **`PowerShell`** ```text title="PowerShell" @{ returnUrl = "http://httpbin.org/get"; authenticationMethod = "none"; email = $variables.SIGNER_EMAIL; userName = $variables.SIGNER_NAME; clientUserId = 1000; } | ConvertTo-Json -Depth 32 > $requestData Invoke-RestMethod ` -Uri "${apiUri}/v2.1/accounts/${accountId}/envelopes/${envelopeId}/views/recipient" ` -Method 'POST' ` -Headers $headers ` -InFile (Resolve-Path $requestData).Path` -OutFile $response Write-Output "Response:" Get-Content $response ``` **`Python`** ```python title="Python" 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) = envelopes_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" view_request = make_recipient_view_request(args[:signer_email], args[:signer_name], signer_client_id, ds_return_url, ds_ping_url) ``` ## Expected response Use the return URL in the JSON response to start the embedded signing session in your browser. **`Sample response`** ```json title="Sample response" { "url": "https://demo.docusign.net/Signing/MTRedeem/v1/54984548-xxxx-xxxx-xxxx-cd0772818bbf?slt=eyJ0eX...m87j8w" } ``` ## 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). * See your options for setting [tabs](/docs/esign-rest-api/esign101/concepts/tabs) and learn more about [working with tabs](/docs/esign-rest-api/reference/envelopes/enveloperecipienttabs). * Learn more about [embedded signing](/docs/esign-rest-api/esign101/concepts/embedding). * See how to [Go-Live](/docs/esign-rest-api/go-live) with a completed app and find the base path for API calls in the production environment.