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
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:
- 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.
- 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.
Requirements:
- At least one recipient must be configured (name, email, and role).
- A document must be selected.
- Signature tags should be placed in the document template to specify where recipients sign. 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
- 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.
- Recipients are optional in the block configuration -- the owner can add them at runtime within the embedded DocuSign 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
Scroll down in the configuration panel and select the Report that DocuSign should send to recipients.
Reports 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.
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.
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:
| Role | Behaviour |
|---|---|
| Signer | Receives the document and is required to sign it. |
| CC | Receives the signed document via email after all Signers have completed signing. CC recipients cannot sign the document. |
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.
When using Send pre-tagged document to recipients, these tags determine exactly where each recipient signs. When using Require owner to add signatories and tags before sending, the owner can also place and adjust tags within the embedded DocuSign interface at runtime, in addition to (or instead of) pre-placing tags in the template.
| Tag Type | Tag | Example | Meaning |
|---|---|---|---|
| E-Signature | [[signature#_doc#]] | [[signature1_doc1]] | Signature field for the first signatory |
| E-Signature Date | [[signdate#_doc#]] | [[signdate1_doc1]] | Date the signatory signed |
| Signatory Name | [[name#_doc#]] | [[name1_doc1]] | Signatory's name from their account |
| Signatory Initials | [[initials#_doc#]] | [[initials1_doc1]] | Signatory's initials from their account |
| Text Field | [[text#_doc#]] | [[text1_doc1]] | Freeform text input for the signatory |
| Number Field | [[number#_doc#]] | [[number1_doc1]] | Numeric input for the signatory |
| Checkbox Field | [[checkbox#_doc#]] | [[checkbox1_doc1]] | Checkbox for the signatory to check/uncheck |
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.
- Replace the second # (after doc) with the document page number. For rich style templates, this is always 1.
- 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.
If no tags are used, DocuSign will allow the signer to manually place their signature anywhere in the document (PDF documents only).
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.
- Add a text field in a FORM block for the signer's contact number.
- (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.
- Configure the DocuSign block. Enter the variable name of the contact number field in the Phone Number field.
Output Variables
The DocuSign block produces three 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.
| Variable | Description |
|---|---|
| Status | Returns the current status of the DocuSign envelope (e.g. Sent, Completed, Declined). This can be used with the Wait block to pause the workflow until a particular status is reached -- for example, waiting until the envelope is Completed before uploading the signed document to SharePoint or triggering the next step. |
| Signed Document | Returns the signed document once all signatories have completed signing. This can be passed to subsequent blocks (e.g. for storage, email attachment, or further processing). |
| Signed Date | Returns the date the document was signed. |
Limitations
| Limitation | Details |
|---|---|
| Public assessments and external users | Require owner to add signatories and tags before sending is not supported for public assessments or external users. Public assessment URLs are accessible without authentication, and external users lack the Checkbox session context required for the embedded interface. |
| Subject line length | DocuSign limits the email subject line to 100 characters. |
| No back-navigation after sending | Once the envelope is sent via Require owner to add signatories and tags before sending, the user cannot navigate back to the DocuSign preparation page. |
| Session expiry | Embedded sessions have a 10-minute duration (a DocuSign-imposed limit). Users are notified before expiry and can refresh the session if it expires. |
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.
- Log into Checkbox.
- Click your username in the top right, then go to Account Settings.
- Click Integrations on the left panel.
- Click the docusign tab.
- Click Add an Account.
- Select your environment (DocuSign Demo or DocuSign Production). We recommend setting up an account for each.
- 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).
- 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.
| Status | Description |
|---|---|
| Completed | All recipients have completed the envelope. |
| Correct | Opened by the sender for correction. Signing is paused. |
| Created | Draft state -- not yet sent for signing. |
| Declined | Declined by one of the recipients. |
| Delivered | All recipients have viewed the document(s) via the DocuSign signing website (not email delivery). |
| Sent | Email notification sent to at least one recipient. Remains until all recipients have viewed it. |
| Signed | All recipients have signed. Temporary state before automatic move to completed. |
| Template | The envelope is a template. |
| Voided | Voided by the sender or expired. |