Skip to navigation
How-to guidesUse tabs

How to set tab values in a template

View as Markdown

This topic demonstrates how to set tab values in a template using the Docusign eSignature REST API.

Run this code example from our Quickstart or launcher projects: Bash, C#, Java, Node.js, PHP, PowerShell, Python, or Ruby.

Required data

Running the code in this how-to requires this data:

Data elementDescription
{API_ACCOUNT_ID}A GUID 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 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://<domain>/restapi
Where <domain> 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.
Documents to be signedYou must provide at least one document to be signed. Document used in this how-to:
{RECIPIENT_ID}A unique string value that you assign to identify each recipient. This value assigns tabs on a per-recipient basis.
Redirect URIA 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 in your Docusign account. See redirect URI for details.
{SIGNER_EMAIL}A string value for the email address associated with your account.
{SIGNER_NAME}A string value for the full name of the signer.
{TEMPLATE_ID}A GUID value that identifies a Docusign template that is used to create a Docusign envelope. This value is automatically generated by Docusign when the template is created.

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.

See 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

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}.

declare -a Headers=('--header' "Authorization: Bearer ${ACCESS_TOKEN}" \
					'--header' "Accept: application/json" \
					'--header' "Content-Type: application/json")

Step 3: Create tabs and custom fields

This how-to uses a template generated previously that defines a few different data tab field types. Create tab objects that match the corresponding tab label to link a newly created tab to an existing template tab.

Set a document ID and page number if you have multiple tabs that need to be set across one or more signing groups. Once ready, bundle all of your created tabs together into a tab object and attach that tab object onto the template role.

declare -A text_custom_fields
text_custom_fields["name"]="app metadata item"
text_custom_fields["required"]="false"
text_custom_fields["show"]="true"
text_custom_fields["value"]="1234567"
declare -A checkbox_tabs
checkbox_tabs["selected1"]="true"
checkbox_tabs["tabLabel1"]="ckAuthorization"
checkbox_tabs["selected2"]="true"
checkbox_tabs["tabLabel2"]="ckAgreement"
declare -A list_tabs
list_tabs["documentId"]="1"
list_tabs["pageNumber"]="1"
list_tabs["tabLabel"]="list"
list_tabs["value"]="green"
declare -A radio_tabs
radio_tabs["selected"]="true"
radio_tabs["value"]="white"
declare -A text_tabs
text_tabs["tabLabel"]="text"
text_tabs["value"]="Jabberywocky!"

Step 4. Construct the request body

Next, create the request body. If using a launcher, you can use an Envelope Definition method to build a valid request body.

Make sure to substitute your valid template ID for {TEMPLATE_ID} and the correlated templateRoles as defined on the template being used.

printf \
'{
    "customFields": {
        "textCustomFields": [{
            "name": "'"${text_custom_fields["name"]}"'",
            "required": "'"${text_custom_fields["required"]}"'",
            "show": "'"${text_custom_fields["show"]}"'",
            "value": "'"${text_custom_fields["value"]}"'"
        }]
    },
    "status": "Sent",
    "templateId": "'"${template_id}"'",
    "templateRoles": [{
        "clientUserId": "1000",
        "email": "'"${SIGNER_EMAIL}"'",
        "name": "'"${SIGNER_NAME}"'",
        "roleName": "signer",
        "tabs": {
            "checkboxTabs": [{
                "selected": "'"${checkbox_tabs["selected1"]}"'",
                "tabLabel": "'"${checkbox_tabs["tabLabel1"]}"'"
            }, {
                "selected": "'"${checkbox_tabs["selected2"]}"'",
                "tabLabel": "'"${checkbox_tabs["tabLabel2"]}"'"
            }],
            "listTabs": [{
                "documentId": "'"${list_tabs["documentId"]}"'",
                "pageNumber": "'"${list_tabs["pageNumber"]}"'",
                "tabLabel": "'"${list_tabs["tabLabel"]}"'",
                "value": "'"${list_tabs["value"]}"'"
            }],
            "radioGroupTabs": [{
                "groupName": "radio1",
                "radios": [{
                    "selected": "'"${radio_tabs["selected"]}"'",
                    "value": "'"${radio_tabs["value"]}"'"
                }]
            }],
            "textTabs": [{
                "tabLabel": "'"${text_tabs["tabLabel"]}"'",
                "value": "'"${text_tabs["value"]}"'"
            }, {
                "bold": "true",
                "documentId": "1",
                "font": "helvetica",
                "fontSize": "size14",
                "height": "23",
                "locked": "false",
                "pageNumber": "1",
                "required": "false",
                "tabId": "name",
                "tabLabel": "added text field",
                "value": "'"${SIGNER_NAME}"'",
                "width": "84",
                "xPosition": "280",
                "yPosition": "172"
            }]
        }
    }, {
        "email": "'"${CC_EMAIL}"'",
        "name": "'"${CC_NAME}"'",
        "roleName": "cc"
    }]
}' >> $request_data

Step 5. Call the eSignature REST API

Now that you have constructed your API headers, make a POST request to the Envelopes:create endpoint to create an envelope.

Here’s how you make the call, but make sure to substitute your API account ID for {ACCOUNT_ID}.

Status=$(curl -w '%{http_code}' -i --request POST ${base_path}/v2.1/accounts/${account_id}/envelopes \
     "${Headers[@]}" \
     --data-binary @${request_data} \
     --output ${response})

Step 6. Create the view request

Create your recipient view request to begin an embedded signing

session. Include your Redirect URI as the return URL, plus the {CLIENT_SIGNER_ID} and the {SIGNER_NAME}.

Use the EnvelopeViews:createRecipient method to return an embedded signing URL by providing your {API_ACCOUNT_ID}, the generated envelope ID from earlier, and the view request you generated previously. Use the embedded signing URL within your application to sign documents.

View the source code for this how-to on GitHub: Bash, C#, Java, Node.js, PHP, PowerShell, Python, or Ruby.

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}

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.

Sample response
{
  "envelopeId": "b4e027e1-xxxx-xxxx-xxxx-ad00ccc8cf3e",
  "uri": "/envelopes/b4e027e1-xxxx-xxxx-xxxx-ad00ccc8cf3e",
  "statusDateTime": "2020-08-12T23:12:01.2930000Z",
  "status": "sent"
}

Next steps