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

· 5 min read

How to request a signature by email using CORS

This topic demonstrates how to send a signature request via an email using JavaScript through your Cross-Origin Resource SharingCross-Origin Resource Sharing, opens in new window (CORS) app within your developer account.

CORS is a technology standard that allows restricted resources such as scripts, forms, or external web pages to be requested from a domain that’s different from the server originating the request. Access to each resource requested via CORS is controlled by CORS access policies set on the server hosting that resource.

CORS enables you to build browser-based applications that can directly call the Docusign eSignature REST API. Your app can use React, Vue, or other browser-based frameworks, or just JavaScript. With CORS, no back-end server is needed.

Prerequisites

To send CORS requests:

  • Since the sender needs Docusign credentials to call the eSignature REST API, the sender needs their own login to the Docusign service. If the sender will also be signing the envelope, or if the signer is physically present with the sender, then this example is applicable.

  • If the signer does not have a Docusign login, then a back-end service (using JWT authentication) should create an access token and use it to call the eSignature REST API. The system administrator for the application’s integration key (client ID) must enable the application to use CORS from the origin(s) the application will be loaded from. For example, if the application’s URL is https://apps.mycompany.com/docusign, the origin https://apps.mycompany.com must be enabled for CORS. See Enable or disable CORS for specific apps for details.

  • The account administrator for every user of your application must also enable CORS access by your application. While the default is to enable CORS access, your users’ administrators can change the default. For instance, suppose your application has 20 users scattered across four companies and five individual eSignature accounts (one of the companies has multiple accounts). In this scenario, five different account administrators must enable CORS access by your application or leave the default setting to CORS enabled by default for all new apps. See Requirements for an app to use CORS for details.

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 GUIDGUID, 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"
}