Docusign - How To - How to request a signature by email with document generation

How to request a signature by email with document generation

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 Docusign Template Assistant for WordDocusign Template Assistant for Word, opens in new window 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.

Required data

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

DATA ELEMENT	DESCRIPTION
{API_ACCOUNT_ID}	A GUIDGUID, opens in new window 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 KeysApps and Keys, opens in new window 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.
DOCX file with sender fields	You 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:
	DOCX file, opens in new window
{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 call shown in this how-to, you need a valid OAuth access token. Docusign supports access tokens for three different OAuth grant types: Authorization Code Grant, Implicit Grant, and JSON Web Token (JWT) Grant. Choose the OAuth grant type appropriate for your scenario.

Step 2. Create an envelope definition from a template

The first step in requesting a signature by email is to create a new envelope definition. Unlike creating an envelope definition without a template, the documents, tabs, and most of the other envelope data will be automatically populated by your chosen template. Instead, you must specify the ID of the template to use and provide the names and emails of the parties acting in each of the roles that the template specifies.

Define a method to create the envelope definition, makeEnvelope, with this code.

1. Python

def make_envelope(cls, args):
    """
    Creates envelope
    args -- parameters for the envelope:
    signer_email, signer_name, signer_client_id
    returns an envelope definition
    """

    # create the envelope definition
    envelope_definition = EnvelopeDefinition(
        status="sent",  # requests that the envelope be created and sent.
        template_id=args["template_id"]
    )
    # Create template role elements to connect the signer and cc recipients
    # to the template
    signer = TemplateRole(
        email=args["signer_email"],
        name=args["signer_name"],
        role_name="signer"
    )
    # Create a cc template role.
    cc = TemplateRole(
        email=args["cc_email"],
        name=args["cc_name"],
        role_name="cc"
    )

    # Add the TemplateRole objects to the envelope object
    envelope_definition.template_roles = [signer, cc]
    return envelope_definition

Step 3. Create and send the envelope

Next, use the envelope definition you just created in the makeEnvelope method to create a new envelope and send it, adding your access token and base path to the request header. Follow these steps: Instantiate the Docusign API client. Set the following default request header to add your access token to all API calls. “Authorization” : “Bearer {ACCESS_TOKEN}” Initialize the Envelopes API. Create an envelope by passing in the generated envelope definition and your account ID to the CreateEnvelope method.

1. Python

def worker(cls, args):
    """
    1. Create the envelope request object
    2. Send the envelope
    """
    envelope_args = args["envelope_args"]
    # 1. Create the envelope request object
    envelope_definition = cls.make_envelope(envelope_args)

    # 2. 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 = envelope_api.create_envelope(account_id=args["account_id"], envelope_definition=envelope_definition)
    envelope_id = results.envelope_id
    return {"envelope_id": envelope_id}

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": "eead435f-xxxx-xxxx-xxxx-25b7d8523d2b",
  "uri": "/envelopes/eead435f-xxxx-xxxx-xxxx-25b7d8523d2b",
  "statusDateTime": "2020-08-18T23:36:26.8830000Z",
  "status": "sent"
}