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 Sharing (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.

Required data

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

Data element	Description
{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.
Documents to be signed	You must provide at least one document to be signed. Document used in this how-to: PDF file
Redirect URI	A 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 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.

CORS-enabled apps should use OAuth Authorization Code Grant, without a secret, with Proof Key for Code Exchange (PKCE) to obtain an access token. A special cors scope is required along with signature when generating your OAuth token request.

JavaScript

class ImplicitGrant {
  constructor(args) {
    this.oAuthServiceProvider = oAuthServiceProvider;
    this.implicitGrantPath = implicitGrantPath;
    this.oAuthClientID = oAuthClientID;
    this.oAuthScopes = oAuthScopes;
    this.oAuthReturnUrl = oAuthReturnUrl;
    this.workingUpdateF = args.workingUpdateF || null;
    // public variables
    this.working = false;
    this.accessToken = null;
    this.accessTokenExpires = null;
    this.errMsg = null;
    // internal
    this._loginWindow = null;
    this._nonce = null;
  }
/*
 * Start the login process in a new browser tab
 */
async login() {
    this.working = true;
    this.errMsg = null;
    if (this.workingUpdateF) {
        this.workingUpdateF(this.working);
    }
    // Get a random nonce to use with OAuth call
    // See https://oauth.net/articles/authentication/#access-token-injection
    // Using https://www.random.org/clients/http/
    this._nonce = Date.now(); // default nonce
    this._nonce = (await this.randomNonce()) || this._nonce;
    const url =
      `${this.oAuthServiceProvider}${this.implicitGrantPath}` +
      `?response_type=token` +
      `&scope=${this.oAuthScopes}` +
      `&client_id=${this.oAuthClientID}` +
      `&redirect_uri=${this.oAuthReturnUrl}` +
      `&state=${this._nonce}`;
    this._loginWindow = window.open(url, "_blank");
    const newTab = this._loginWindow;
    if (!newTab || newTab.closed || typeof newTab.closed=='undefined') {
        // POPUP BLOCKED
        alert ("Please enable the popup login window.")
    }
    this._loginWindow.focus();
}

Step 2. Construct the request body

Construct the request body by defining a method named createEnvelope that creates the envelope definition. The createEnvelope method demonstrates how to:

Create a new, signable PDF document in code
Attach your document to the envelope
Set signer data
Create and assign a SignHere tab to the signer

Define the createEnvelope method with this code.

JavaScript

const signer = {
  name: {SIGNER_NAME},
  email: {SIGNER_EMAIL},
};
const envelopeId = await createEnvelope(signer);
async function createEnvelope({ name, email}) {
  const docB64 = await data.callApi.getDocB64(docUrl); // fetch a document
  const req = {
    emailSubject: "Please sign the attached document",
    status: "sent",
    documents: [
      {
        name: "Example document",
        documentBase64: docB64,
        fileExtension: "pdf",
        documentId: "1",
      }
    ],
    recipients: {
      signers: [
        {
          email: email,
          name: name,
          customFields: ["field1: value 1", "field2: value 2"],
          recipientId: "1",
          tabs: {
            signHereTabs: [
              {
                anchorString: "/sig1/",
                anchorXOffset: "20",
                anchorUnits: "pixels"
              }
            ],
            checkboxTabs: [
              {
                anchorString: "/sig1/",
                anchorXOffset: "180",
                anchorUnits: "pixels",
                tabLabel: "checkbox 1",
                tabGroupLabels: ["checkbox group"]
              },
              {
                anchorString: "/sig1/",
                anchorXOffset: "180",
                anchorYOffset: "20",
                anchorUnits: "pixels",
                tabLabel: "checkbox 2",
                tabGroupLabels: ["checkbox group"]
              }
            ],
            tabGroups: [
              {
                groupLabel: "checkbox group",
                groupRule: "SelectExactly",
                minimumRequired: "1",
                maximumAllowed: "1",
                validationMessage: "Please check one option",
                tabScope: "document",
                pageNumber: "1",
                documentId: "1"
              }
            ],
            textTabs: [
              {
                anchorString: "/sig1/",
                anchorXOffset: "195",
                anchorUnits: "pixels",
                value: "I agree with license 1",
                locked: "true",
                font: "Helvetica",
                fontSize: "Size12",
                bold: "true"
              },
              {
                anchorString: "/sig1/",
                anchorXOffset: "195",
                anchorYOffset: "20",
                anchorUnits: "pixels",
                value: "I agree with license 2",
                locked: "true",
                font: "Helvetica",
                fontSize:"Size12",
                bold: "true"
              },
              {
                anchorString: "/sig1/",
                anchorXOffset: "20",
                anchorYOffset: "50",
                anchorUnits: "pixels",
                bold: "true",
                font: "Helvetica",
                fontSize: "Size14",
                fontColor: "NavyBlue",
                value: "Addendum\n‣ Item 1\n‣ Item 2\nThis is a multi-line read-only text field"
              }
            ]
          }
        }
      ]
    }
  }
}

Step 3. Call the eSignature REST API to create the envelope

Now that you have constructed your API headers and request body, you can

make a POST request to the Envelopes:create method and include the request body to send

a remote envelope using CORS.

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

JavaScript

const apiMethod = `/accounts/${data.userInfo.defaultAccount}/envelopes`;
const httpMethod = "POST";
const results = await data.callApi.callApiJson({
    apiMethod: apiMethod,
    httpMethod: httpMethod,
    req: req
});
if (results === false) {
    errMsg(data.callApi.errMsg);
    return false;
}
if (logLevel > 0) {
    htmlMsg(
        `<p>Envelope created. Response:</p><p><pre><code>${JSON.stringify(
            results,
            null,
            4
        )}</code></pre></p>`
    );
}
return results.envelopeId;

Expected response

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": "54984548-xxxx-xxxx-xxxx-cd0772818bbf"
}

Next steps

See

How to request a signature through your CORS-enabled browser app

.
See How to get an access token using Public Authorization Code Grant.
Learn more about Single-page applications and CORS.