---
name: docusign-salesforce
description: Build a production-grade DocuSign to Salesforce integration covering architecture, the step-by-step build with Apex code, field mapping, API and governor limits, security, monitoring, and the pitfalls to design out. Use when connecting, building, or debugging a DocuSign and Salesforce integration.
---

# DocuSign to Salesforce integration

> Cloudsheer's delivery playbook for DocuSign on Salesforce, distilled from 22 client projects and 119 delivery tasks. Apply it as the reference approach when building this integration.

## Overview

Send agreements and order forms for signature from Salesforce, with signed docs and status flowing back. We have shipped it across 23 client projects and 119 build tasks.

The value is that the action happens automatically from the record your team already works in, with the result tracked back in Salesforce.

We deploy the managed package the right way: sandbox first, licenses and permission sets assigned, templates and layouts configured, and automation wrapped around it so it fits your process.

Every DocuSign build is delivered by a senior Salesforce architect on a fixed price, tested end to end in a sandbox, deployed to your org, and backed by 30 days of hypercare. You own the result: documented, source-controlled, and free of black-box middleware lock-in.

## Integration facts

**Connects via:**
- DocuSign eSignature for Salesforce managed package (namespace dfsle), delivered via DocuSign Apps Launcher
- Admin connects a DocuSign account through a Salesforce Connected App / OAuth
- Apex Toolkit (dfsle classes) for code-driven envelope generation
- DocuSign Connect webhooks push envelope/recipient status back into Salesforce

**Package:** DocuSign eSignature for Salesforce (namespace dfsle)

**Authentication:** OAuth 2.0: the admin authorizes a DocuSign account via a Connected App; the Apex Toolkit manages the token flow internally so developers do not write auth code

**API type:** REST+Webhooks

**API base:** `https://{server}.docusign.net/restapi/v2.1 (Apex Toolkit abstracts this)`

**Key endpoints:**
- `dfsle.EnvelopeService (build/send envelopes)`
- `dfsle.Envelope / dfsle.Recipient / dfsle.Document classes`
- `POST /accounts/{accountId}/envelopes`
- `DocuSign Connect (webhook publisher)`

**Webhook and platform events:**
- `envelope-sent`
- `envelope-delivered`
- `envelope-completed`
- `envelope-declined`
- `envelope-voided`
- `recipient-completed`

**Official docs:** https://developers.docusign.com/docs/salesforce/

## Prerequisites

- A Salesforce edition with API access (Enterprise, Unlimited, or Developer)
- The managed package, installed in a sandbox first
- A dedicated sandbox to build and test in
- A DocuSign account on a plan with API access
- System Administrator access on both systems
- A dedicated integration user with a minimum-access permission set
- Agreement on the objects, fields, and sync direction for the DocuSign data

## Architecture

Data flows left to right through four lanes:

1. **Sources:** Record triggers, DocuSign templates, Envelope events
2. **Integration layer:** Envelope generation, Field mappings, Status callbacks, Error handling
3. **Salesforce:** Opportunity, Account, Agreement records, Files
4. **Outcomes:** Signed agreements on record, Real-time envelope status, No re-keying

## How it works at runtime

1. **Trigger from a record** `[In Salesforce]`: A flow or button on an Opportunity, Account, or custom object starts an envelope from a template.
   - Note: `A record-triggered flow or Quick Action calls the DocuSign managed package.`
2. **Merge Salesforce data** `[In Salesforce]`: Field mappings populate the template so names, amounts, and terms are correct every time.
   - Note: `Salesforce fields are mapped to DocuSign template tabs before sending.`
3. **Send for signature** `[In transit]`: The envelope is sent to one or more signers with the correct routing order.
   - Note: `The package calls the DocuSign eSignature API over an authenticated connection.`
4. **Signer completes** `[In DocuSign]`: The recipient signs, and DocuSign tracks the envelope status through to completion.
   - Note: `DocuSign hosts the signing session and records the audit trail.`
5. **Status and document return** `[In Salesforce]`: Envelope status and the signed PDF are written back onto the Salesforce record automatically.
   - Note: `DocuSign Connect posts status back; the signed PDF is stored as a File on the record.`

## Step-by-step build

### Step 1: Plan the integration and prerequisites

We line up licenses and access before installing anything.

- A Salesforce edition compatible with the package, and a sandbox to install into first
- A DocuSign account and admin rights on both systems
- The records, templates, and outcomes agreed up front

### Step 2: Install the managed package

We install DocuSign the safe way.

- Install from AppExchange into a sandbox first, choosing Install for All Users
- Approve the third-party access it requests, and note the API or remote endpoints it uses

> **Pro tip: sandbox first** Install the managed package in a sandbox first and choose Install for All Users, so you can configure and test safely before anything touches production.

### Step 3: Assign licenses and permission sets

We give the right users the right access.

- Assign the package licenses and its permission sets to the integration user and the end users who need it

### Step 4: Authenticate to DocuSign

We connect the package to your DocuSign account securely.

- Authenticate DocuSign via OAuth and configure the org-wide and per-user settings
- Confirm any Named Credential or Remote Site the package relies on is configured

### Step 5: Configure objects, templates, and layouts

We set DocuSign up around how you actually work.

- Configure the DocuSign-specific pieces such as templates, gateways, or components
- Add the Lightning components and actions to the right page layouts
- Map Salesforce fields into DocuSign so documents and records are accurate every time

### Step 6: Build automation around the package

We make DocuSign fire from the right place and write results back.

- Record-triggered flows or Quick Actions invoke the package's invocable methods
- Status and results are written back onto the Salesforce record automatically

Reference implementation (`snippets/GenerateDocument.cls`):

```apex
public class GenerateDocument {
  @InvocableMethod(label='Generate document via package')
  public static void run(List<Id> recordIds) {
    // a record-triggered flow calls this; it hands off to the managed package
    for (Id recId : recordIds) {
      pkg.DocumentService.createFromTemplate(recId, 'Order Form');
    }
  }
}
```

### Step 7: Test in a sandbox

We validate the full flow before go-live.

- Run real scenarios end to end and confirm the records, documents, and callbacks

### Step 8: Deploy and monitor

We ship it and support it.

- Deploy configuration via change sets and assign permission sets in production
- Monitor callbacks and errors, with 30 days of support

## Data model

| Object | Purpose | Key fields |
| --- | --- | --- |
| `agreement` | The primary Salesforce record DocuSign data maps onto. | `External_Id__c, Name, Status` |
| `Account` | Matched or created for the customer or company behind the record. | `Name, External_Id__c` |
| `Error_Log__c (custom)` | Captures every request, response, and failure so anything can be replayed. | `Payload__c, Status__c, Related_Id__c` |

Salesforce objects typically in play: `dfsle__EnvelopeStatus__c`, `dfsle__RecipientStatus__c`, `Opportunity, Contract, Account, Contact, Lead or custom source`

## Field mapping (example)

| DocuSign | Salesforce | Notes |
| --- | --- | --- |
| Salesforce agreement | `DocuSign record` | Direction: Salesforce to DocuSign |
| Record id | `DocuSign external reference` | Stored back on the record |
| Key fields | `DocuSign fields` | Mapped per template |
| Status | `DocuSign status` | Written back on completion |
| Created / updated at | `LastModifiedDate` | Enables delta sync and audit |
| Owner or rep | `agreement.OwnerId` | Assignment rules or a default owner |

Tailor the full mapping to the org. Always upsert on an external-id field so retries are idempotent.

## API and rate limits

### DocuSign-specific

- Default eSignature API ~1,000 calls/hour per plan; burst ~500 calls per 30s
- Connect webhook events are queued but capped
- Salesforce Apex callout limits apply when the Toolkit runs synchronously (100 callouts/txn, 120s)

### Salesforce platform

- The managed package uses its own API budget. We confirm the limits on your plan before go-live.
- DocuSign rate limits apply to bulk operations. We chunk batches to stay within them.

## Security checklist

- Secrets stored in Named Credentials and permission sets, never in code or metadata
- A least-privilege integration user, with field-level security and sharing scoped tight
- All traffic over TLS, with signature verification on inbound events
- Shield Platform Encryption available for sensitive fields
- A full audit trail: every request and response logged for traceability
- Every automation runs as a dedicated integration user, so actions are attributable and revocable
- Sandbox-first delivery and change-set deployment keep production changes reviewed and controlled

## Monitoring and reliability

- Every request and response is logged to a custom Error Log object, tagged with the related record id.
- Failed calls retry with exponential backoff; anything still failing lands in a dead-letter queue for review.
- Idempotency keys guarantee a retried or duplicate event never double-posts a record.
- A dashboard surfaces failures, latency, and volume so problems are caught before users notice.
- Optional email or Slack alerts fire on repeated failures or a stalled sync.

## Testing and deployment

- Apex unit tests with HttpCalloutMock cover the success path, failure handling, and a 200-record bulk case, at 75 percent or higher coverage.
- The full flow is validated in a sandbox against real sample data and the edge cases that matter.
- A parallel run reconciles the integration against your live system before cutover.
- Everything deploys through change sets or an SFDX and CI pipeline, under version control.
- Permission sets, sharing, and Named Credentials are configured in production, then we run 30 days of monitored hypercare.

## Pitfalls to design out

- **Config lost between orgs:** Deploy configuration via change sets and document the setup.
- **Users cannot see the feature:** Assign the package license and permission set to the right users.
- **Vendor limits hit unexpectedly:** Confirm the API and volume limits on your plan before go-live.
- **No visibility when it breaks:** We log every call and surface failures on a dashboard with alerts, so an issue never goes unnoticed.
- **Reporting drifts from reality:** External-id keys and a delta timestamp keep Salesforce and the source reconciled, so reports stay trustworthy.

### DocuSign-specific gotchas

- Two namespaces exist (current dfsle vs legacy dsfs), causing migration and field-mapping differences
- DocuSign Connect must be enabled and the Connected App authorized or statuses never write back
- Toolkit calls count against BOTH DocuSign and Salesforce limits; bulk sending can throttle

## FAQ

**How do you authenticate DocuSign with Salesforce?**

We connect DocuSign using the managed package with OAuth and store every secret in Salesforce Named Credentials with a permission set, so nothing is hard-coded or shipped in metadata.

**Does the DocuSign integration handle bulk volume?**

Yes. All Apex is bulkified, volume moves to Queueable or Batch Apex, and we respect the Salesforce governor limits (SOQL, DML, and callout caps per transaction).

**How do you prevent duplicate records?**

We upsert on a unique external-id field, so a retried or duplicate payload is idempotent and never creates a second agreement.

**How is the integration tested and deployed?**

Apex tests with HttpCalloutMock cover the success, failure, and a 200-record bulk case (75 percent plus coverage). We deploy via change sets or an SFDX and CI pipeline.

**What happens if DocuSign or Salesforce is briefly down?**

Failed calls retry with backoff and land in an Error Log object with alerting, so nothing is lost and any event can be replayed.

**Do we still need custom code?**

Usually only a thin layer: record-triggered flows or a small invocable Apex method to fire the package and write results back. The heavy lifting is the managed package.

---

Maintained by [Cloudsheer](https://www.cloudsheer.com). Full illustrated guide: [DocuSign technical guide](https://www.cloudsheer.com/integrations/docusign/technical-guide). Want it built for you at a fixed price? [Book a free 30-minute call](https://cal.com/cloudsheer-consulting/30min?overlayCalendar=true).