DocuSign Block

Note: The DocuSign block replaces the DocuSign functionality previously found in the E-SIGN block. Existing E-SIGN blocks configured with DocuSign will continue to work during the migration period. Learn more about migrating from the E-SIGN block.

SKIP AHEAD TO
Why use DocuSign in Checkbox?
Selecting a DocuSign Account
Choosing a Sending Mode
Selecting a Document
Configuring Recipients
Email Subject and Body
DocuSign Tag Syntax
Adding 2FA for Signing
Output Variables
Limitations
Integration Setup
Envelope Statuses

Why use DocuSign in Checkbox?

DocuSign allows you to send documents for electronic signature directly from a Checkbox workflow. Recipients receive an email with a link to sign the document, removing the need for physical paper documents and creating more efficiency with handling signed documents.

The DocuSign block supports two sending modes:

1. Send pre-tagged document to recipients -- The document is pre-configured with signature tags and recipient details in Studio, then sent automatically when the workflow reaches the DocuSign block.
2. Require owner to add signatories and tags before sending -- The DocuSign envelope preparation interface is embedded directly within Checkbox at runtime, allowing the workflow owner to review the document, add recipients, and place signature tags before sending.

Prerequisites

Before using the DocuSign block, you must enable the DocuSign integration for your Checkbox environment. See Integration Setup for step-by-step instructions.

Selecting a DocuSign Account

Each DocuSign block requires you to select which connected DocuSign account envelopes will be sent from. The block provides two separate account selectors:

• Preview & Test Teams -- The DocuSign account used when the workflow is run in preview mode or by a test team. This allows you to test the signing flow without sending envelopes from your official account.
• Published -- The DocuSign account used when the workflow is published and run by end users in production.

This separation lets you use a sandbox or test account during development and switch to an official account for live workflows. Different DocuSign blocks within the same workflow can also use different accounts, giving you flexibility when a workflow involves multiple signing steps that need to originate from different accounts.

Choosing a Sending Mode

The DocuSign block supports two sending modes. Choose the one that best fits your workflow.

Mode 1: Send Pre-Tagged Document to Recipients

The workflow author configures everything in Studio -- recipients, document, tags, and email content. When a user runs the workflow and reaches the DocuSign block, the envelope is assembled and sent automatically based on that configuration. The user running the workflow does not interact with DocuSign directly.

Use this mode when:

• The recipients and their signing locations are known ahead of time or can be resolved from variables.
• You want a fully automated, hands-off signing step.
• You want to send several documents in one envelope.

Requirements:

• At least one recipient must be configured (name, email, and role).
• At least one document must be added. See Selecting Documents.
• Signature tags should be placed in each document template to specify where recipients sign (see DocuSign Tag Syntax). If no tags are used, DocuSign will allow the signer to manually place their signature.

Mode 2: Require Owner to Add Signatories and Tags Before Sending

When this mode is enabled, the workflow pauses at the DocuSign block and presents the user with the DocuSign interface embedded directly within the Checkbox page. This is the same DocuSign envelope preparation experience users would find in DocuSign itself, but accessed without leaving Checkbox.

From this embedded interface, the user can:

• Review the uploaded document pre-filled with any generated content
• Add, edit, or remove recipients and their signing roles
• Place and adjust signature tags and other fields on the document by dragging them into position
• Send the envelope when ready

Once the envelope is sent, the workflow automatically advances to the next step.

Use this mode when:

• Recipients or tag placements are not known until runtime.
• A human review step is needed before the envelope is dispatched.
• The workflow owner needs to customise the envelope on a case-by-case basis.

Requirements:

• A document must be selected. This mode sends one document. To send several documents in one envelope, use Send pre-tagged document to recipients.
• Recipients are optional in the block configuration -- the owner can add them at runtime within the embedded DocuSign interface.
• The document doesn't need DocuSign tags. The owner places the fields in the embedded interface.

Session Timeout Handling

The embedded DocuSign session has a 10-minute duration (DocuSign restriction). Checkbox handles this as follows:

• Before timeout: The user is notified that their session is about to expire, giving them time to complete their work.
• On timeout: An expired session modal is displayed with an option to refresh the session and continue where they left off.
• On page refresh: If the user refreshes the browser while the embedded session is active, Checkbox restores the embedded view so the user can continue.

Resuming an Incomplete Envelope

If the user navigates away from the workflow before sending the envelope, they can resume the assessment later. The embedded DocuSign interface will reload, allowing them to pick up where they left off. Once the envelope is sent, the user cannot navigate back to the preparation page.

Selecting a Document

Documents can be uploaded via a Document Upload field in a Form block or generated using the Doc Gen block. Learn more about Rich Style Document Templates and specifying E-Signature Location on a Document.

How many documents you can send depends on the sending mode.

Send pre-tagged document to recipients can send up to 20 documents in one envelope. Under Documents, add each document you want to send:

1. Select Add Document.
2. In Document template, select the document to send.
3. Check the Document variable name. This output variable will hold the signed copy of the document. Checkbox fills in a name, and you can change it.
4. Repeat for each document.
   
   

All the documents go into one envelope in the order they're listed. Recipients get one email and sign them all in one session.

A document doesn't need signature tags. If you add one without tags, recipients can read it in the envelope but aren't asked to sign it. For example, you might send a board memo alongside the documents a director signs.

If a document's variable is empty when the workflow reaches the DocuSign block, Checkbox leaves that document out and sends the rest. This can happen, for example, when a condition skips the Doc Gen block that creates it. At least one document must contain a file. Add every document the envelope could need to this list in Studio. You can't add documents to the list at runtime.

Require owner to add signatories and tags before sending sends one document. The block shows a single Select document field instead of the Documents list. If you need to send several documents together, switch to Send pre-tagged document to recipients.

Configuring Recipients

Enter the name and email of each recipient. You can use static text or variables:

• TXT# variables (e.g. {{TXT1}})

  LIST# variables (e.g. {{LIST1}})

  USER# variables (e.g. {{USER1.name}}, {{USER1.email}})

Variables must be enclosed in curly braces {{ }} to be valid. Learn more about Operators and Variables.

Recipients are set once for the whole envelope, not for each document. Every recipient can see every document in the envelope, including documents they don't sign. If a recipient mustn't see a document, send that document from a separate DocuSign block.

Reminder: Recipients are required when using Send pre-tagged document to recipients, and optional when using Require owner to add signatories and tags before sending.

Signing Order

The Set Signing Order toggle controls whether recipients sign sequentially or simultaneously. This mirrors DocuSign's native signing order functionality.

• On: Recipients sign in the order they are listed. For example, if Jane Wilson is the first recipient and {{USER12.name}} is the second, Jane will receive the signing request first. Once she has signed, the next recipient will be notified.
• Off: All recipients receive the signing request at the same time and can sign in any order.

If a LIST variable is used, all recipients within the list are treated as a single position in the signing order. When signing order is on, they all sign simultaneously at that position before the next recipient is notified. When signing order is off, they are sent alongside all other recipients.

Recipient Roles

Assign each recipient one of the following roles:

LIST Variables and Merge Blocks

LIST variables are typically used from Merge blocks that have merged the names and emails of recipients from text input fields in FORM blocks. If LIST variables are used, the list of names and the list of emails must correspond to each other by order and have the same length. Learn more about Merge blocks.

Email Subject and Body

Provide a custom email subject and body for the signing notification sent to recipients.

• Referenced variables such as {{Client}} and system variables can be used to personalise the notification. Learn more about Operators and Variables and see the list of all system variables.
• Limitation: The subject line can hold up to 100 characters (DocuSign limitation).

When using Require owner to add signatories and tags before sending with no pre-configured recipients, the email subject and body fields are managed within the embedded DocuSign interface at runtime.

DocuSign Tag Syntax

DocuSign tags specify where signature fields and other elements appear in your document. Tags can be inserted into Rich Document Templates.

Tag syntax is only used with Send pre-tagged document to recipients, where the tags determine exactly where each recipient signs. With Require owner to add signatories and tags before sending, you don't need it. The owner drags signature fields onto the document in the embedded DocuSign interface instead.

How to Use Tags

• Replace the first # with the signatory number (matching the recipient order). E.g. [[signature1_doc1]] for the first signatory, [[signature2_doc1]] for the second. Use the same number for a recipient in every document in the envelope. If Jane is the first recipient, her tags are [[signature1_doc1]] in each document she signs.
• Replace the second # (after doc) with the document page number. For rich style templates, this is always 1. This number doesn't refer to the document's position in the Documents list. A rich style template uses _doc1 whether it's the first document in the envelope or the fifth.
• If a tag is on the same line as other text, the tag must be uniquely typographically emphasised (e.g. italicised).
• A space must be placed before any tag on a line.
• Change the text colour of tags to white to prevent signatures from overlapping the tag text.

When an envelope has several documents, add each recipient's tags only to the documents they sign. A recipient with no tags in a document isn't asked to sign that document.

If no tags are used, DocuSign will allow the signer to manually place their signature anywhere in the document (PDF documents only). In an envelope with several documents, this happens only when a signer has no tags in any of them. They can then place their signature anywhere in the envelope, so make sure every signer has tags in at least one document.

Learn more about E-Signature Tags in a Document.

Adding 2FA Requirement for Signing

If your DocuSign account has Two-Factor Authentication (2FA) enabled, you can require signers to verify their identity via phone.

1. Add a text field in a FORM block for the signer's contact number.
2. (Optional) Apply a Regular Expression for format validation on the text field (e.g. ^\+(?:[1-9]\d{0,2})[-\s]?(?:\d{1,4}[-\s]?){2,5}\d{1,4}$). The number must be in international format, beginning with + followed by the country code.
3. Configure the DocuSign block. Enter the variable name of the contact number field in the Phone Number field.

Output Variables

The DocuSign block produces output variables that can be referenced by subsequent blocks in the workflow. These are found under the Variable Name field in the block's SETTINGS panel. With Send pre-tagged document to recipients, the signed-document variables are named in the Documents list instead.

Signed documents and the certificate are available only after the envelope reaches Completed. Add a Wait block that waits for Completed before any later block uses them.

Limitations

Integration Setup

Enabling DocuSign requires action from a DocuSign Developer account holder and a Checkbox Account Administrator.

Note: If you do not have a DocuSign Developer account, you can sign up for one here.

It is best practice to connect both a DocuSign Demo and a DocuSign Production account. Demo is used for testing; Production is used for sending live envelopes.

Connecting DocuSign to Checkbox

Note: You must be a Checkbox Account Administrator.

1. Log into Checkbox.
2. Click your username in the top right, then go to Account Settings.

3. Click Integrations on the left panel.

4. Click the docusign tab.

5. Click Add an Account.

6. Select your environment (DocuSign Demo or DocuSign Production). We recommend setting up an account for each.

7. You will be redirected to DocuSign. Log in using the account you want envelopes sent from. This is also the account DocuSign will charge for Production envelopes (does not apply to Demo).

8. After logging in you will be redirected back to Checkbox. You may now use this DocuSign account in any Checkbox Project Team.

Envelope Statuses

These are the possible values returned by the Status output variable.

Related Articles

• E-Signature Tags in a Document
• Project Team: Download Signed Documents
• Rich Style Document Templates
• Operators and Variables
• Merge Blocks