Skip to navigation
How-to guidesSend a signature request (remote signing)

How to request a signature by email with document generation

View as Markdown
eSignature REST API 2.1 only

This topic demonstrates how to request a signature for an envelope created from a template that uses the Document generation feature. This feature enables you to create agreements that can be populated with customized data. The template includes a document that contains placeholders, known as sender fields. For each envelope created from the template, the sender fields in the document are dynamically populated with data specified by the sender. The document in this example also includes a dynamic table—a feature that enables senders to supply values for a table that can have a different number of rows for each envelope. The signature request in this how-to is sent to the recipient via email, a process known as remote signing.

If you have created a template using the recommended Agreement Template Builder or the Docusign Template Assistant for Word add-in, you can skip steps 2 through 4 in this how-to.

Important: You must have document generation enabled for your account. See Document generation for more information.

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.
DOCX file with sender fieldsYou must provide at least one document to be signed that includes document generation sender fields. Currently, only DOCX files are supported. Document used in this how-to:
{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.

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. Create a template

This template definition includes a signer role that serves as a placeholder for the envelope recipients. This placeholder role contains an ID, a role name, and a routing order that determines the order of delivery. The template definition also includes a description, name, email subject, recipients, and status. The template document and signer tabs will be defined in subsequent steps. Create the template using the Templates:create API call, substituting your API account ID for ACCOUNT_ID, your base path for BASE_PATH, and the access token from step 1 for ACCESS_TOKEN.

printf \
'{
    "description": "Example template created via the API",
    "name": "Example document generation template",
    "shared": false,
    "emailSubject": "Please sign this document",
    "status": "created",
    "recipients": {
         "signers": [
              {
                 "recipientId": "1", "roleName": "signer", "routingOrder": "1"
              }
          ]
    }
}' >> $request_data
Status=$(curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
    --header "Content-Type: application/json" \
    --data-binary @${request_data} \
    --request POST ${base_path}/v2.1/accounts/${account_id}/templates \
    --output ${response})
if [[ "$Status" -gt "201" ]] ; then
  echo ""
	echo ""
	cat $response
	exit 0
fi
# pull out the template id
template_id=`cat $response | grep templateId | sed 's/.*\"templateId\":\"//' | sed 's/\",.*//'`

Step 3. Add a document with sender fields to your template

The document provided in this call should have sender fields, which will be automatically detected. See Methods for creating documents for more information on how to create a document with a dynamic table and sender fields. For your sender fields to be automatically detected, you must add your document to the template separately from the Templates:create call in Step 2. After adding a Base64-encoded document to the request body, call TemplateDocuments:update, substituting the template ID obtained from the Templates:create API call for TEMPLATE_ID.

# Fetch document and encode
cat demo_documents/Offer_Letter_Dynamic_Table.docx | base64 > $doc1_base64
printf \
'{
  "documents": [
        {
            "documentBase64": "' >> $request_data
            cat $doc1_base64 >> $request_data
            printf '",
            "documentId": "1", "fileExtension": "docx", "order":"1","pages":"1",
            "name": "OfferLetterDemo.docx"
        }
    ]
}' >> $request_data
Status=$(curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data-binary @${request_data} \
  --request PUT ${base_path}/v2.1/accounts/${account_id}/templates/${template_id}/documents/1 \
  --output ${response})

Step 4. Add tabs to the template

Now that the template contains a document, add tabs for the placeholder recipient. In the request body, define a signHere tab and a dateSigned tab using Auto-place (anchor tagging). Then make a call to TemplateRecipientTabs:create.

printf \
'{
    "signHereTabs": [
        {
            "anchorString": "Employee Signature",
            "anchorUnits": "pixels",
            "anchorXOffset": "5",
            "anchorYOffset": "-22"
        }
    ],
    "dateSignedTabs": [
        {
            "anchorString": "Date Signed",
            "anchorUnits": "pixels",
            "anchorYOffset": "-22"
        }
    ]
}' >> $request_data
Status=$(curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data-binary @${request_data} \
  --request POST ${base_path}/v2.1/accounts/${account_id}/templates/${template_id}/recipients/1/tabs \
  --output ${response})

Step 5. Create an envelope draft from a template

When creating an envelope definition from a template, you must specify the template ID that was returned from the Templates:create call in Step 2. If you created the template using the Agreement Template Builder or the Docusign Template Assistant for Word, you can obtain the template ID by logging in to the eSignature web app, selecting Templates from the top navigation menu, opening the template, and selecting the Template ID link. You also must provide the name and email of the party acting in the signer role that the template specifies. Set the status field to created since you will be updating this draft in the following steps. Then create the envelope draft with a call to Envelopes:create, substituting your signer’s email for SIGNER_EMAIL and their name for SIGNER_NAME.

printf \
'{
    "templateId": "'"${template_id}"'",
    "templateRoles": [
        {
            "email": "'"${SIGNER_EMAIL}"'",
            "name": "'"${SIGNER_NAME}"'",
            "roleName": "signer"
        }
    ],
    "status": "created"
}' >> $request_data
echo ""
echo "Sending the envelope request to DocuSign..."
Status=$(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})
if [[ "$Status" -gt "201" ]] ; then
  echo ""
	echo "Envelope creation failed."
	echo ""
	cat $response
	exit 0
fi
envelope_id=`cat $response | grep envelopeId | sed 's/.*\"envelopeId\":\"//' | sed 's/\",.*//'`

Step 6. Get DocGenFormFields

Make a call to DocumentGeneration:getEnvelopeDocGenFormFields to receive a list of the docGenFormFields on the document. You will also need the documentId value returned in the response of this API call to complete the next step.

Status=$(curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
      --header "Accept: application/json" \
      --request GET ${base_path}/v2.1/accounts/${account_id}/envelopes/${envelope_id}/docGenFormFields \
      --output ${response})
echo $Status
if [[ "$Status" -gt "201" ]] ; then
  echo ""
	echo "Failed to fetch docGenFormFields."
	echo ""
	cat $response
	exit 0
fi
echo "DocGenFormFields: "
cat $response
# Retrieve the document id
document_id=`cat $response | grep documentId | sed 's/.*\"documentId\":\"//' | sed 's/\",.*//'`

Step 7. Merge sender fields with the eSignature REST API

Update the value of the docGenFormFields specified in the response of the previous step with the appropriate sender data. Then, use the DocumentGeneration:updateEnvelopeDocGenFormFields method to dynamically generate a document with the data included in the request.

printf \
'{
  "docGenFormFields": [
    {
      "documentId": "'"${document_id}"'",
      "docGenFormFieldList": [
        {
          "name": "Candidate_Name",
          "value": "'"${CANDIDATE_NAME}"'"
        },
        {
          "name": "Job_Title",
          "value": "'"${JOB_TITLE}"'"
        },
        {
          "name": "Manager_Name",
          "value": "'"${MANAGER_NAME}"'"
        },
        {
          "name": "Start_Date",
          "value": "'"${START_DATE}"'"
        },
        {
          "name": "Compensation_Package",
          "type": "TableRow",
          "rowValues": [
            {
              "docGenFormFieldList": [
                {
                  "name": "Compensation_Component",
                  "value": "Salary"
                },
                {
                  "name": "Details",
                  "value": "$'"${SALARY}"'"
                }
              ]
            },
            {
              "docGenFormFieldList": [
                {
                  "name": "Compensation_Component",
                  "value": "Bonus"
                },
                {
                  "name": "Details",
                  "value": "20%%"
                }
              ]
            },
            {
              "docGenFormFieldList": [
                {
                  "name": "Compensation_Component",
                  "value": "RSUs"
                },
                {
                  "name": "Details",
                  "value": '${RSUS}'
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}' >> $request_data
Status=$(curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
      --header "Content-Type: application/json" \
      --data-binary @${request_data} \
      --request PUT ${base_path}/v2.1/accounts/${account_id}/envelopes/${envelope_id}/docgenformfields \
      --output ${response})

Step 8. Send the envelope with the eSignature REST API

Send the envelope by setting the status to sent using the Envelopes:update method.

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

printf \
'{
    "status": "sent"
}' >> $request_data
Status=$(curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data-binary @${request_data} \
  --request PUT ${base_path}/v2.1/accounts/${account_id}/envelopes/${envelope_id} \
  --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.

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
{"envelopeId":"6d6fc561-xxxx-xxxx-xxxx-901a1b4b92a4"}

Next steps