Docusign

What your agents can doCopy Anchor Link

Helios agents can call Docusign APIs with the connected user's permissions. Helios attaches the access token to each request. The specs cover the eSignature REST API v2.1, Click, Admin, Rooms, Workspaces, Web Forms, Workflow Builder, Agreement Manager, Connected Fields, and Monitor APIs.

• Send an envelope from a template, or with documents included in the request
• Check an envelope's status, see who still has to sign, and download the signed documents as PDF files
• Resend an envelope, correct its recipients, or void it
• Create and update templates, elastic templates, rooms, and workspaces
• Start a Workflow Builder workflow, or create a web form instance to send
• Add, change, or close users in your organization with the Admin API

API calls need the complete path. eSignature paths start with /restapi/v2.1 and Click paths with /clickapi/v1. Calls to the other APIs need their full API URL.

Each API works only when the account has the product. Rooms needs a Docusign Rooms account, and Docusign offers the Web Forms API on developer accounts but only on some production plans. The Admin API needs Admin access and an organization administrator. The Monitor API needs the Docusign JWT Grant method and a user who is an organization administrator or a security reports administrator in one organization only. Docusign sells Monitor separately for production accounts.

This integration does not index the Notary, CLM, or ID Evidence APIs.

AuthenticationCopy Anchor Link

Both methods reach every API above except Monitor, which only accepts a JWT grant.

Both methods start with an app on the Apps and Keys page. Each app has an integration key. To open the page, sign in to Docusign, click Admin, and select Apps and Keys under Integrations. Docusign creates new apps in a developer account. To use one with a production account, take it through Docusign's Go-Live review. The production copy keeps the same integration key but needs its own secret key or RSA key pair, and its own redirect URI.

Docusign also offers the Developer Console, in open beta, which manages integration keys for both environments. The steps below use the Apps and Keys page.

See Integration authentication for how credentials are stored and injected.

ScopesCopy Anchor Link

Helios asks for these scopes with both methods. You don't turn them on in Docusign. The user approves them when they sign in or give consent.

The OAuth app also asks for extended, which gives each new refresh token a full lifetime. The JWT grant also asks for impersonation, which lets the app act as the user.

Check Admin access to also ask for the Admin API scopes. Docusign lets only organization administrators use the Admin API.

Docusign JWT GrantCopy Anchor Link

You need admin access to the Docusign account to use the Apps and Keys page. You also need to sign in once as the user Helios will act as.

1. On the Apps and Keys page, click Add App and Integration Key and name the app.

2. Under User Application, answer Yes to whether the app can securely store a client secret. New apps start this way. Docusign needs it for the consent link in step 5.

3. Under Service Integration, click Generate RSA and copy the private key. Docusign shows it once.

4. Under Additional Settings, click Add URI and add a redirect URI, such as https://www.docusign.com. The consent link needs one. Save the app.

5. Sign in to Docusign as the user Helios should act as, and open this link once. Replace the integration key and redirect URI with your own. For a production account, use account.docusign.com instead of account-d.docusign.com.

   Copy Text

   https://account-d.docusign.com/oauth/auth?response_type=code&scope=signature%20click.manage%20click.send%20dtr.rooms.read%20dtr.rooms.write%20dtr.documents.read%20dtr.documents.write%20dtr.profile.read%20dtr.profile.write%20dtr.company.read%20dtr.company.write%20room_forms%20webforms_read%20webforms_instance_read%20webforms_instance_write%20aow_manage%20adm_store_unified_repo_read%20adm_store_unified_repo_write%20models_read%20document_uploader_read%20document_uploader_write%20public_dms_document_read%20search_read%20impersonation&client_id=<integration key>&redirect_uri=<redirect URI>

   If you will check Admin access, the user must be an organization administrator, and the link needs the Admin API scopes too:

   Copy Text

   https://account-d.docusign.com/oauth/auth?response_type=code&scope=signature%20click.manage%20click.send%20dtr.rooms.read%20dtr.rooms.write%20dtr.documents.read%20dtr.documents.write%20dtr.profile.read%20dtr.profile.write%20dtr.company.read%20dtr.company.write%20room_forms%20webforms_read%20webforms_instance_read%20webforms_instance_write%20aow_manage%20adm_store_unified_repo_read%20adm_store_unified_repo_write%20models_read%20document_uploader_read%20document_uploader_write%20public_dms_document_read%20search_read%20impersonation%20organization_read%20group_read%20permission_read%20user_read%20user_write%20account_read%20account_write%20domain_read%20identity_provider_read%20user_data_redact%20asset_group_account_read%20asset_group_account_clone_write%20asset_group_account_clone_read%20organization_sub_account_read%20organization_sub_account_write%20connect_org_config_read_api%20connect_org_config_write_api%20connect_org_oauth_read_api%20connect_org_oauth_write_api%20connect_org_hmac_read_api%20connect_org_hmac_write_api&client_id=<integration key>&redirect_uri=<redirect URI>

   Click Accept. Docusign then redirects to the redirect URI, and that page can show an error. Consent is saved anyway.

6. In Helios, choose Docusign JWT Grant and fill in:

   • Integration Key: the app's integration key.
   • User ID: the user who gave consent in step 5. The Apps and Keys page shows the User ID of the user who is signed in.
   • API Account ID and Account Base URI: from the Apps and Keys page, such as https://demo.docusign.net for a developer account.
   • RSA Private Key: the private key from step 3, including the BEGIN and END lines.
   • Connect HMAC Key: optional. Needed for triggers.
   • Admin access: check it to use the Admin API.

7. Save.

Helios requests an access token with the scopes from the consent link. The token lasts an hour, and Helios requests a new one 15 minutes before it expires. If you check Admin access later, open the consent link with the Admin API scopes first.

If you delete the RSA key pair in Docusign, generate a new one and enter its private key through Manage.

Your own Docusign OAuth appCopy Anchor Link

You need admin access to the Docusign account to use the Apps and Keys page.

1. On the Apps and Keys page, click Add App and Integration Key and name the app.

2. Under User Application, answer Yes to whether the app can securely store a client secret. Then click Add Secret Key and copy the key. Docusign shows it once.

3. Under Additional Settings, click Add URI and add this redirect URI. Save the app.

   Copy Text

   https://api.heliosapp.com/integrations/docusign/oauth_callback

4. In Helios, choose Your own Docusign OAuth app and fill in:

   • Integration Key and Secret Key: from the app.
   • Account Base URI: https://demo.docusign.net for a developer account. Leave it empty for a production account.
   • API Account ID: optional. Leave it empty to connect the user's default account.
   • Connect HMAC Key: optional. Needed for triggers.
   • Admin access: check it to use the Admin API. An organization administrator must then sign in.

5. Save, then sign in to Docusign and approve access.

After you approve, Helios stores the account's own base URI. Access tokens last 8 hours, and Helios renews them with the refresh token. Helios also refreshes the token every week, because a Docusign refresh token expires about 30 days after it is issued.

If you replace the secret key in Docusign, or check or uncheck Admin access, update the connection through Manage and click Re-connect.

TriggersCopy Anchor Link

Docusign can start a Workflow when something happens in the account. When you save a connection that has a Connect HMAC Key, Helios creates a Docusign Connect configuration for the account, named Helios followed by the connection's ID, and subscribes it to every event below. You only create the HMAC key. Deleting the connection removes the configuration.

Triggers need three things:

• An account administrator. Only Docusign account administrators can manage Connect. For the JWT grant, the User ID must belong to an administrator. For the OAuth app, an administrator must approve access.
• Connect on the account. Developer accounts include it. Docusign warns that a production plan can lack features that developer accounts have. Check that Connect appears under Admin → Integrations before you rely on triggers.
• An HMAC key. In Docusign, open Admin → Integrations → Connect, select Connect Keys, and click Add Secret Key. Copy the key into Connect HMAC Key on the connection. Docusign shows it once.

If you add the HMAC key later, enter it through Manage and save. Helios then creates the configuration. Until then, the trigger picker shows every Docusign event as unavailable.

If Docusign refuses the full list of events, Helios subscribes the configuration to the events in Docusign's own example configuration instead. The trigger picker then shows the other events as unavailable.

Some events only arrive when the account uses the feature that sends them: elastic templates for clickwrap events, SMS delivery for sms events, EU qualified signatures for identity_verification events, Workflow Builder for workflow events, data verification extension apps for extension.executed, Docusign Notary for notary_session events, and Workspaces for workspace_upload_request events.

Every filter is optional.

• Subject matches the envelope's email subject, such as NDA*. Case matters. A * stops at /, so for subjects like Order Form 10/09, use ** after the slash, as in Order Form*/**.
• Sender email matches the address of the envelope's sender, such as *@sales.example.com. Case doesn't matter.
• Template name matches the template's name. Case matters.
• Elastic template ID, workflow ID, and workspace ID match the ID of the elastic template, the Workflow Builder workflow, or the workspace. Case matters.

The configuration covers every user in the account. Envelope and recipient events include the envelope's subject, sender, recipients, and custom fields, except envelope.removed and envelope.reminder_sent. The other events include the IDs and fields that Docusign lists for them in its event reference.

Docusign signs each delivery with every HMAC key on the account, in the X-DocuSign-Signature-1, X-DocuSign-Signature-2, and later headers. Helios accepts a delivery when one of them matches your key. Docusign doesn't sign a timestamp or send a delivery ID. Helios treats deliveries with the same event, item, recipient, and generation time as one, and drops the repeats. The item is the envelope, template, agreement, workflow instance, or upload request the event is about.

When a delivery fails, Docusign retries it after 5, 10, 20, and 40 minutes, then after 1 hour, 2 hours, and 1 day, and then once a day for 15 days.

Check that it worksCopy Anchor Link

• The connection: after you save, the connection's status shows Connected. Error means Docusign rejected the credentials. See Common errors, then click Test Connection to check again.
• The Connect configuration: in Docusign, open Admin → Integrations → Connect and select Configurations. A configuration named Helios followed by the connection's ID should be listed. Select Dashboard on the same page to see each delivery and any error.
• A trigger:
  1. Add envelope.sent to a workflow with no filters.
  2. Send a test envelope in Docusign.
  3. Check that a run starts. Then open the connection in Helios and click Webhook events to see the event.

Common errorsCopy Anchor Link

LimitsCopy Anchor Link

Docusign limits each account to 3,000 API calls an hour by default, and to 200 calls in 30 seconds in a developer account or 500 in production. An app can request an envelope's status at most once every 15 minutes. Use triggers instead of asking an agent to poll. See Docusign's API resource limits.