DocuSign integration

The portal has an in-house signing flow and an optional connection to your DocuSign account. Choose the workflow your business needs; neither choice makes a template attorney-reviewed or guarantees legal compliance for your transaction.

Built-in signing vs DocuSign — when to use each

If you require a particular legal standard, certification, or signing order, verify it with the provider and your adviser. Do not infer ESIGN, HIPAA, or other compliance from selecting an option in this form.

Connecting your account

1. Open Settings → DocuSign.
2. Check the Environment selection. Environments without configured credentials, and production on deployments that block it, are unavailable. Ask your deployment administrator to complete the setup requirements shown on the page.
3. Choose Connect/ Reconnect and complete DocuSign's authorization flow.
4. Review the connection result. Use the connection test and template-sync controls if the page reports that authorization worked but the initial sync did not.

The integration stores account information and encrypted authorization credentials. You enter your DocuSign password on DocuSign's page, not in the contract composer.

Saved authorization describes the stored account configuration. Test connection checks whether those credentials can still access that account. A successful test applies to that request; it does not continuously monitor the connection or verify webhook delivery. Incomplete saved credentials require reconnecting.

Changing environment clears the current connection when allowed, so reconnect to the selected environment. Rejected changes preserve the saved connection. Switching environments or disconnecting does not automatically void existing envelopes: recipients may still sign in DocuSign, while portal status sync and signed-document downloads may stop until you reconnect to the correct account.

Deployment setup

Create an integration key in a DocuSign developer account. For production, promote that key through DocuSign Go-Live. The promoted integration key keeps the same GUID; configure its production client secret and redirect URIs separately. See DocuSign's production configuration guidance.

Configure the matching DOCUSIGN_DEMO_INTEGRATION_KEY and DOCUSIGN_DEMO_SECRET_KEY, or DOCUSIGN_PROD_INTEGRATION_KEY and DOCUSIGN_PROD_SECRET_KEY, on the server. Register the exact callback URL shown in settings. The app uses DOCUSIGN_REDIRECT_URI, falling back to /api/auth/docusign/callback on NEXT_PUBLIC_APP_URL. A valid SETTINGS_ENCRYPTION_KEY is required to save authorization credentials.

Production also requires the deployment guard to allow it. The canonical production host is allowed by default. DOCUSIGN_ALLOW_PRODUCTION=false blocks production; true explicitly enables it. Demo remains available when its credentials are configured.

Configure Docusign Connect separately

OAuth authorization does not configure Docusign Connect. In the matching DocuSign account, configure Connect to send signed JSON envelope events to /api/webhooks/docusign on the app's public origin. Set the matching HMAC signing key on the server as DOCUSIGN_CONNECT_DEMO_HMAC_KEY or DOCUSIGN_CONNECT_PROD_HMAC_KEY; DOCUSIGN_CONNECT_HMAC_KEY remains supported for an existing shared configuration.

Prefer the environment-specific keys. When retaining the legacy shared key, also set DOCUSIGN_CONNECT_HMAC_ENV to demo or production; staging uses demo. The JSON event must include data.accountId. The webhook checks both that account and the HMAC environment against the envelope's saved account binding. Missing or mismatched scope is acknowledged without changing the contract, and an account-scoped envelope sync can reconcile it. A saved shared key by itself is not sufficient webhook configuration.

The settings page can confirm that a server key is configured, but cannot certify delivery or that the provider uses the same key. Verify delivery in DocuSign Connect after setup.

How to route a contract through DocuSign

In New contract, choose DocuSign as the signing method. The supported paths are:

• A template from the connected DocuSign account with exactly one named signer role and no additional recipients. Templates with multiple signers or other recipients must be sent directly from DocuSign.
• An uploaded PDF, up to 9 MB, with a readable text layer containing the literal \s1\ anchor at the client's signature location. Encrypted, unreadable, and anchorless files are rejected before sending.
• A portal Markdown template rendered to PDF for the envelope, including its client signature, date, and initial fields.

This composer supports one client signer and rejects co-signer fields for DocuSign sends. Review native templates in DocuSign and uploaded files in the PDF preview. For an agreement rendered from portal Markdown, enter the company signer name and company signature; the portal embeds that signature in the outgoing PDF. It does not add a company signature to uploaded PDFs or native DocuSign templates. Those documents must already include any required company signature, and you must confirm that they are ready for the client. Change orders do not add this company pre-signature.

The portal retains the exact outgoing PDF for uploads and Markdown documents, separately from the later signed copy. Use Open source PDF on the contract record to review those original bytes. Native template documents remain in their DocuSign envelope.

Choose an expiration between 1 and 120 days. If document preparation is delayed, sending uses the whole days remaining until the prepared deadline, rounded up. A document whose deadline has passed cannot be sent from that attempt. The local deadline is an estimate based on when sending starts until DocuSign supplies its own expiry time. Checking a pending send does not restart its expiry period.

When sending succeeds, DocuSign issues the signing emails and the portal keeps a linked contract record. A preview or attempted send is not proof that an envelope was delivered.

If the response is lost or the local update fails, the original contract and send attempt are retained. Open that record and use Check send status. Recovery looks up the original transaction and does not create another envelope. Keep the original composer and document details if preparation itself needs a retry. DocuSign transaction lookup is available for seven days; an unresolved attempt after that needs administrator reconciliation in DocuSign before a replacement is prepared.

What syncs back

The DocuSign webhook at /api/webhooks/docusign processes supported envelope events and updates the linked contract's status. On completion, the portal attempts to retrieve and store the signed document for the client.

Webhook delivery, a valid connection, and successful document download/storage are separate dependencies. A signed envelope in DocuSign may temporarily lack a portal PDF if synchronization fails. Review the detail page and retry/connection controls; do not interpret a missing download as proof that nobody signed.

Completion records durable work for project/deposit bookkeeping, the signed PDF, notifications, the signed-copy receipt, and connected Google calendar synchronization. Each step can retry independently through the side-effect dispatcher; calendar synchronization waits for the local bookkeeping to finish. A downloaded PDF does not mark financial bookkeeping complete. The receipt confirms the signature and provides its signed-copy link; it does not confirm that an invoice was paid. It retains portal access without sending an additional sign-in-link email to clients who already have an account. Historical signed copies can have their bookkeeping repaired without sending old receipts again.

The webhook verifies configured HMAC signatures. This helps authenticate provider events; it is not a blanket guarantee that all documents are legally valid.

Importing externally-signed envelopes

From the DocuSign tools on Contracts, use Sync sent envelopes. The sync matches the first recipient's email to an existing client in the organization:

• A matching client allows the envelope to be linked/imported.
• An unmatched envelope is skipped; add the correct client and sync again.
• Known envelopes are refreshed rather than intentionally duplicated.

Review the sync summary and the imported contract's status/artifact. This is not an unlimited, guaranteed import of everything ever stored in your DocuSign account.

Envelopes created outside the portal are imported as document mirrors: importing them does not create a project, deposit, or signing receipt. Envelopes originating from a recoverable portal send retain that original contract's project and terms.

Templates

Use Sync templates now in DocuSign settings or the relevant sync control in Contract templates. Synced templates are provider-backed/read-only in the portal. Edit their source in DocuSign, then synchronize again.

Sync reads every page before replacing the local template cache. If a page fails, pagination is inconsistent, or the connection changes during sync, the cache is preserved and the sync must be retried. Reconnect or refresh settings first if the account changed.

In-flight visibility

Open /admin/contracts/<id> to inspect the linked envelope status and available actions. The provider status reflects the latest successfully processed update, not a guarantee of instantaneous synchronization. Open the envelope in DocuSign when you need to confirm its provider-side recipients, routing, or completion certificate.

Disconnecting

Disconnecting prevents new provider API operations and can prevent document downloads or refreshes. Envelopes already sent may still be acted on within DocuSign, but do not assume portal synchronization and artifact retrieval will keep working without a connection.

Plan disconnection around in-flight agreements and retain required records first. Reconnect if the portal reports expired/rejected authorization.

Troubleshooting

• Connection test fails: use Reconnect and review the selected environment.
• Template missing: sync templates; check that it belongs to the connected account.
• Send could not be confirmed: open the retained contract and use Check send status to recover the original attempt.
• Uploaded PDF rejected: use a readable, unencrypted PDF of up to 9 MB with a \s1\ text anchor where the client signs.
• Signed envelope has no PDF here: confirm the connection and provider completion, then investigate synchronization/download status.
• Webhook not arriving: ask the deployment administrator to verify the public callback and DocuSign Connect signing configuration.