Docusign - How To - How to request a signature by email using a template

How to request a signature by email using a template

This topic demonstrates how to use a template to create an envelope and send it by email. When a recipient receives and signs an envelope by email, the process is called remote signing.

Required data

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

DATA ELEMENT	DESCRIPTION
{API_ACCOUNT_ID}	A GUID, 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.
{CC_RECIPIENT_EMAIL}	A string value for the email address of the cc recipient.
{CC_RECIPIENT_NAME}	A string value for the name of the cc recipient.
{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.
{TEMPLATE_ID}	A GUID, opens in new window 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 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"
}