Skip to main content

Configuring the DocuSign Integration in MetaLocator

Configure the MetaLocator DocuSign integration, including OAuth setup, RSA keys, templates, signer roles, and embedded signing.

P
Written by Pankaj Kushwaha

The MetaLocator DocuSign integration allows MetaLocator to automatically generate and send documents for electronic signature using DocuSign templates.

This article explains how to:

  • Generate the required DocuSign Configuration Values

  • Create and configure a DocuSign template

  • Configure DocuSign settings inside MetaLocator

Before Getting Started

Before configuring the integration, ensure the following items are available:

  • A DocuSign developer account

  • A DocuSign production account

  • Permission to create DocuSign Apps and Integration Keys

  • A MetaLocator Enterprise account with the DocuSign integration enabled

  • Access to edit the MetaLocator interface that will use DocuSign

Using Developer and Production DocuSign Values

DocuSign developer and production environments are separate. Use developer account values while testing the integration. After testing, promote the Integration Key to production and use production account values in the live MetaLocator interface.

The Integration Key is promoted from the developer account to the production account during the DocuSign Go-Live process.

The following values must be reviewed or generated in the production account:

  • RSA Private Key

  • Impersonated User ID

  • Template ID

  • DocuSign OAuth Base URL

  • DocuSign OAuth Redirect URI

Generating the Private Key / RSA Key

Generate the RSA key when creating a new App and Integration Key. This app allows MetaLocator to securely communicate with the DocuSign API to generate and send signature requests automatically.

Create the DocuSign App and Integration Key

  1. Log in to the DocuSign developer account.

  2. From the main navigation, select Admin.

  3. Select Apps and Keys from the sidebar navigation on the left.

  4. Select Add App and Integration Key.

  5. Enter an app name.

  6. Under Integration Type, select Private application integration.

  7. Under Authentication, configure the application for JWT authentication.

  8. Under Service Integration, select Generate RSA.

  9. Copy and securely store the generated RSA Private Key.

  10. Under Additional settings, add the required Redirect URIs.

  11. Under CORS Configuration, enable Allow CORS for OAuth calls if the DocuSign account requires it for the configured consent flow.

  12. Select Save.

Important: DocuSign only displays the RSA Private Key once when it is generated. Store the key securely immediately after downloading it. If the key is lost, a new RSA key must be generated.

Locating the Integration Key

Once a new App and Integration Key have been added:

  1. From the main navigation, select Admin.

  2. Select Apps and Keys.

  3. Find the Integration key for the app that was created.

Locating the Impersonated User ID

The Impersonated User ID is the DocuSign account user that MetaLocator acts on behalf of when sending envelopes and generating signature requests.

To locate the User ID:

  1. From the main navigation, select Admin.

  2. Select Apps and Keys.

  3. Locate the User ID value.

Locating the Template ID

Each environment generates its own Template ID.

To locate the Template ID:

  1. Open the DocuSign template to be used for the integration.

  2. Locate the Template ID value.

After testing in the developer environment:

Move the application from the developer account to the production account.

  1. From the main navigation, select Admin.

  2. Under Apps and Keys.

  3. Select Go-Live Account for the App and Integration key that needs to be pushed to production

4. A login modal appears, log in to the Production account

5. After a successful log in, go to the production account, under Apps and Keys, a new integration key should be added. This is the Integration key that was pushed from the developer account to production account

To generate the RSA key again in production

  1. Log in to the DocuSign production account.

  2. From the main navigation, select Admin.

  3. Select Apps and Keys.

  4. Select the Action menu, then select Edit.

5. Configure the application settings as shown below (same as developer account)

Important: Save the RSA key at this step securely

Create and configure a DocuSign template

MetaLocator can work with either:

  • A new DocuSign template

  • An existing DocuSign template

  • A MetaLocator-provided template JSON file

To create or upload a template:

  1. Log in to DocuSign.

  2. From the main navigation, select Templates.

  3. Create a new template or open an existing template.

  4. To use a MetaLocator-provided template, select Upload Template and upload the provided JSON file.

Note: If the option to upload a template is not available, manually create and configure the template using the steps below.

Once a new template has been created, configure signer and CC recipient roles inside the template.

The DocuSign template must include one required recipient role as signer.

Recipient Role: signer

The signer role represents the user signing the document.

Configure the role as follows:

  • Add the recipient role as signer

  • Leave the Name field blank

  • Leave the Email field blank

  • Set the recipient type to Needs to Sign

MetaLocator dynamically populates the signer name and email address when the document is generated.

Recipient Role: ml_docuSign_CC (optional)

The ml_docuSign_CC role sends a signed copy of the document to the email associated with the contacted location.

The ml_docuSign_CC role is optional. Add this role only when signed copies should be sent to the contacted location.

Configure the role as follows:

  • Add the recipient role as ml_docuSign_CC

  • Leave the Name field blank

  • Leave the Email field blank

  • Set the recipient type to Receives a Copy

Important: The recipient role names must match exactly:

  • signer

  • ml_docuSign_CC

Additional hard-coded recipients may also be added if needed. For example, to notify and send the signed document to the organization’s support team

Configure the role as follows:

  • Add a recipient role

  • Add the Name of the recipient

  • Add the Email of the recipient

  • Set the recipient type to Receives a Copy

After configuring recipients, select Next or Save and Close.

Add MetaLocator dynamic fields to a template

MetaLocator can automatically populate document fields using dynamic DocuSign Data Labels.

To add dynamic fields:

  1. Log in to DocuSign.

  2. From the main navigation, select Templates.

  3. Open the template.

  4. Select Edit.

  5. Set the recipient scope to signer.

  6. Add a Text field to the document.

  7. Select the field.

  8. Configure the Data Label value.

Supported Dynamic Field Values

The following Data Label values are currently supported by MetaLocator.

Location Address: This is the address of the location being contacted. Use location_address as the data-label value inside the DocuSign template

Location Email: This is the email address of the location being contacted. Use location_email as the data-label value inside the DocuSign template

Location Name: This is the name of the location being contacted. Use location_name as the data-label value inside the DocuSign template

Location Phone: This is the phone number of the location being contacted. Use location_phone as the data-label value inside the DocuSign template

Signer Name: This is the name of the signer contacting the location. Use lead_name as the data-label value inside the DocuSign template

Signer Email: This is the email of the signer contacting the location. Use lead_email as the data-label value inside the DocuSign template

Adding Signature and Date Fields

Signature and date fields can be added directly from the DocuSign Fields panel.

  1. Add a Signature field.

  2. Add a Date Signed field.

  3. Position the fields in the appropriate location in the document.

These fields do not require Data Label values.

Saving the Template

After configuring all fields and recipients, select Save and Close.

Configure DocuSign settings inside MetaLocator

After creating the DocuSign app and template, enter the DocuSign values in the MetaLocator interface that will use the integration.

  1. Log in to MetaLocator.

  2. From the main navigation, select Interfaces.

  3. Select Edit for the interface that will use DocuSign.

  4. Select the Lead Generation tab.

  5. Scroll to Contact Form Template.

  6. Select More Leads Features.

  7. Locate the DocuSign Integration section.

Enable DocuSign Integration

Set Enable DocuSign Integration to Yes. This enables the DocuSign signing flow for the selected interface.

DocuSign Client ID

Enter the DocuSign Integration Key value. Use the developer Integration Key while testing. Use the production Integration Key after moving the DocuSign application to production.

DocuSign Impersonated User ID

Enter the DocuSign Impersonated User ID for the user MetaLocator should act on behalf of when creating envelopes. Use the developer account User ID while testing. Use the production account User ID after deployment.

DocuSign OAuth Base URL

Enter the DocuSign OAuth base URL for the environment.

Use:

  • account-d.DocuSign.com for DocuSign developer/demo accounts

  • account.DocuSign.com for DocuSign production accounts

Do not include a trailing slash.

DocuSign OAuth Redirect URI

This is the OAuth redirect URI used during the consent flow. Since MetaLocator is using JWT, DocuSign requires the account owner to grant consent once. The default URL in MetaLocator is https://developers.DocuSign.com/platform/auth/consent and this is DocuSign’s own consent helper page.

Add the OAuth redirect URI to the DocuSign app. To add the OAuth redirect URI, follow these steps:

  1. Log in to the DocuSign account (Developer account or Production)

  2. Go to Apps and Keys

  3. Edit the app used for MetaLocator DocuSign integration

  4. Add the Redirect URIs under Additional settings. Add the DocuSign default consent URL: https://developers.DocuSign.com/platform/auth/consent

  5. Save the app

DocuSign Private Key

Enter the RSA Private Key generated from the DocuSign app. Use the full private key value generated by DocuSign.

Use the RSA Private Key from the same DocuSign environment configured in DocuSign OAuth Base URL.

DocuSign Return URL

Enter the URL where DocuSign should send the signer after the signing session is completed or canceled.

This is commonly the live MetaLocator interface URL or a confirmation page on the website.

If this field is left blank, MetaLocator uses the interface lead link when available, then falls back to the interface URL.

DocuSign Leads Notification Delay (in days)

Enter the number of days MetaLocator should delay lead notifications while waiting for the DocuSign envelope to be completed.

When this value is greater than 0, MetaLocator also sets the DocuSign envelope expiration period using the same number of days. When the envelope is completed, MetaLocator releases the delayed lead notification.

Use 0 to avoid delaying lead notifications.

DocuSign Send CC Emails

Set DocuSign Send CC Emails to Yes to send a completed copy of the document to the contacted location.

When enabled, the DocuSign template must include a carbon copy recipient role named: ml_docuSign_CC

Set this option to No when the template does not include the ml_docuSign_CC role.

Add the DocuSign field to the lead form

  1. Log in to MetaLocator.

  2. From the main navigation, select Interfaces.

  3. Select Edit for the interface that will use DocuSign.

  4. Select the Basic Settings tab.

  5. Locate the Leads section.

  6. Select Add Field.

  7. Under Special Fields, select DocuSign.

  8. Select Add Field.

  9. Select the new DocuSign field to edit its settings.

DocuSign_template_id

Enter the DocuSign Template ID for the template MetaLocator should use.

Use the developer template ID while testing. Use the production template ID after deployment.

Target Custom Field

Optionally enter the custom field value that should trigger the DocuSign signing flow.

Use this setting when the DocuSign flow should only appear after a specific lead form selection, such as a consent option.

Final Checklist

Use this checklist before enabling the DocuSign integration in a live MetaLocator interface.

DocuSign account configuration

Confirm the following items are configured in DocuSign:

  1. DocuSign App and Integration Key

    • A DocuSign app exists in the correct environment.

    • The Integration Key is available.

    • For production, the Integration Key has been promoted through the DocuSign Go-Live process.

  2. RSA Private Key

    • An RSA Private Key has been generated for the DocuSign app.

    • The key has been copied and stored securely.

    • The production key is used for production MetaLocator interfaces.

  3. Impersonated User ID

    • The correct DocuSign User ID has been copied from Admin > Apps and Keys.

    • The developer User ID is used only for testing.

    • The production User ID is used for live implementations.

  4. OAuth Base URL

    • Developer/demo environment uses:
      ​account-d.docusign.com

    • Production environment uses:
      ​account.docusign.com

  5. OAuth Redirect URI

  6. DocuSign template

    • The template exists in the same DocuSign environment used by MetaLocator.

    • The correct Template ID has been copied.

    • For production, use the production template ID.

  7. Template recipient roles

    • The required signer role exists and is named exactly:
      ​signer

    • The signer recipient type is Needs to Sign.

    • If CC emails are enabled, the optional CC role exists and is named exactly:
      ​ml_docuSign_CC

    • The ml_docuSign_CC recipient type is Receives a Copy.

  8. Template Data Labels

    • Any dynamic fields use supported DocuSign Data Label values:

      • lead_name

      • lead_email

      • location_name

      • location_email

      • location_address

      • location_phone

    • Signature and date fields have been added where required.

MetaLocator interface configuration

Confirm the following items are configured in MetaLocator:

  1. Enable DocuSign Integration

    • Set to Yes in the interface Lead Generation settings.

  2. DocuSign Client ID

    • Contains the DocuSign Integration Key.

  3. DocuSign Impersonated User ID

    • Contains the DocuSign User ID for the selected environment.

  4. DocuSign OAuth Base URL

    • Uses account-d.docusign.com for developer/demo testing.

    • Uses account.docusign.com for production.

  5. DocuSign OAuth Redirect URI

    • Matches a redirect URI configured in the DocuSign app.

  6. DocuSign Private Key

    • Contains the RSA Private Key from the same DocuSign environment used by the interface.

  7. DocuSign Return URL

    • Contains the URL where signers should return after completing or canceling the signing session.

    • This can be the MetaLocator interface URL or a custom confirmation page.

  8. DocuSign Leads Notification Delay (in days)

    • Set to 0 if lead notifications should not be delayed.

    • Set to the intended number of days if lead notifications should wait for DocuSign completion.

  9. DocuSign Send CC Emails

    • Set to Yes only when the DocuSign template includes the ml_docuSign_CC role.

    • Set to No when the template does not include a CC role.

  10. DocuSign field in the lead form

    • A DocuSign special field has been added to the interface lead form.

    • The field’s docusign_template_id value matches the DocuSign template ID for the selected environment.

    • Optional display fields such as Link Text, Tooltip, and Help text have been configured.

Test the DocuSign integration

  1. Open the live or preview version of the MetaLocator interface.

  2. Submit a test lead that triggers the DocuSign field.

  3. Select the DocuSign signing link.

  4. Confirm that DocuSign opens an embedded signing session.

  5. Complete the signing session.

  6. Confirm that the signer is redirected to the configured DocuSign Return URL.

  7. Confirm that the lead record updates after DocuSign sends the completion event.

  8. If DocuSign Send CC Emails is enabled, confirm that the contacted location receives the completed copy.

Related Articles
Publishing MetaLocator leads to HubSpot
Customizing Lead Emails in MetaLocator
Did this answer your question?