# API Reference **Project**: Salesforce Composite Envelope Builder **Version**: 1.1 **Date**: February 23, 2026 (updated March 11, 2026) --- ## 1. Docusign REST API Integration ### 1.1 Base Endpoint **Production**: ``` https://na3.docusign.net/restapi/v2.1 ``` **Sandbox**: ``` https://demo.docusign.net/restapi/v2.1 ``` **Note**: Replace `na3` with your account's data center (na2, na3, eu1, etc.) --- ## 2. Create Composite Envelope ### 2.1 HTTP Request **Method**: POST **Endpoint**: `/accounts/{accountId}/envelopes` **Content-Type**: `application/json` **Authorization**: `Bearer {access_token}` ### 2.2 Request Headers ```http POST /restapi/v2.1/accounts/12345678-abcd-1234-abcd-1234567890ab/envelopes HTTP/1.1 Host: na3.docusign.net Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IjY4MTg... Content-Type: application/json Accept: application/json ``` ### 2.3 Request Body (Composite Templates) #### Minimum Example (2 templates) ```json { "status": "sent", "emailSubject": "Please review and sign these forms", "compositeTemplates": [ { "compositeTemplateId": "1", "serverTemplates": [ { "sequence": "1", "templateId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } ] }, { "compositeTemplateId": "2", "serverTemplates": [ { "sequence": "2", "templateId": "b2c3d4e5-f6g7-8901-bcde-fg2345678901" } ] } ] } ``` #### Advanced Example (with merge fields) ```json { "status": "sent", "emailSubject": "Please review and sign these forms", "compositeTemplates": [ { "compositeTemplateId": "1", "serverTemplates": [ { "sequence": "1", "templateId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } ], "inlineTemplates": [ { "sequence": "1", "customFields": { "textCustomFields": [ { "name": "SalesforceRecordId", "value": "0018V00000ABC123" }, { "name": "CaseNumber", "value": "00001234" } ] } } ] } ] } ``` ### 2.4 Response #### Success (201 Created) ```json { "envelopeId": "f9876543-21ab-cdef-0123-456789abcdef", "uri": "/envelopes/f9876543-21ab-cdef-0123-456789abcdef", "statusDateTime": "2026-02-23T12:34:56.789Z", "status": "sent" } ``` #### Error (400 Bad Request) ```json { "errorCode": "INVALID_REQUEST_PARAMETER", "message": "The request contained at least one invalid parameter. The template with ID 'invalid-id' does not exist." } ``` #### Error (401 Unauthorized) ```json { "errorCode": "USER_AUTHENTICATION_FAILED", "message": "One or both of Username and Password are invalid." } ``` --- ## 3. Composite Template Structure ### 3.1 Key Concepts **compositeTemplates** (array): - Each element represents a server template to include in the envelope - Order in array determines document order in envelope **compositeTemplateId** (string): - Unique identifier for this composite template within the request - Can be any string (recommend using sequence numbers: "1", "2", "3") **serverTemplates** (array): - References pre-existing templates in your Docusign account - Must include `templateId` (GUID from Docusign) **sequence** (string): - Determines document order within the envelope - "1" = first document, "2" = second, etc. - **Important**: Use strings, not integers **inlineTemplates** (array, optional): - Allows runtime override of template values - Used for custom fields, recipient data, tabs ### 3.2 Recipient Merging **Automatic Merge**: When multiple templates have recipients with the same `roleName`, Docusign automatically merges them into a single recipient. **Example**: - Template A has recipient role: "Signer" - Template B has recipient role: "Signer" - Result: One recipient signs all documents **Requirements for merge**: - Exact match on `roleName` - Same recipient `routingOrder` (signing order) - Merge happens automatically, no additional configuration needed --- ## 4. Authentication ### 4.1 JWT (JSON Web Token) **Preferred method for server-to-server integration** #### Step 1: Generate JWT ```apex // Apex pseudocode String jwt = generateJWT( integrationKey, // From Docusign Apps & Keys userId, // Docusign user GUID rsaPrivateKey, // RSA private key (PEM format) 'https://account-d.docusign.com/oauth/auth', // Sandbox 3600 // Token expiry (1 hour) ); ``` #### Step 2: Exchange JWT for Access Token **Request**: ```http POST /oauth/token HTTP/1.1 Host: account-d.docusign.com Content-Type: application/x-www-form-urlencoded grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion={jwt} ``` **Response**: ```json { "access_token": "eyJ0eXAiOiJNVCIsImFsZyI...", "token_type": "Bearer", "expires_in": 3600 } ``` #### Step 3: Use Access Token ```http Authorization: Bearer eyJ0eXAiOiJNVCIsImFsZyI... ``` ### 4.2 OAuth2 Authorization Code **User-based authentication** (not recommended for this use case) See [Docusign OAuth2 documentation](https://developers.docusign.com/platform/auth/authcode/) for details. --- ## 5. Error Codes ### 5.1 Common Error Codes | Error Code | HTTP | Meaning | Resolution | |------------|------|---------|------------| | `INVALID_REQUEST_PARAMETER` | 400 | Invalid parameter in request | Check JSON structure, template IDs | | `USER_AUTHENTICATION_FAILED` | 401 | Invalid or expired access token | Refresh access token | | `USER_LACKS_PERMISSIONS` | 403 | User doesn't have permission | Check Docusign user permissions | | `RESOURCE_NOT_FOUND` | 404 | Template ID not found | Verify template exists in account | | `DUPLICATE_RESOURCE` | 409 | Duplicate request | Check for duplicate envelope | | `ONESIGNAL_GENERIC_ERROR` | 500 | Docusign server error | Retry after delay | ### 5.2 Rate Limits **Hourly limit**: Varies by plan (1,000 - 10,000+ API calls/hour) **Response header when nearing limit**: ```http X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 50 X-RateLimit-Reset: 1614358800 ``` **Error when limit exceeded**: ```json { "errorCode": "HOURLY_APIINVOCATION_LIMIT_EXCEEDED", "message": "The maximum number of hourly API invocations has been exceeded." } ``` **Mitigation**: - Implement exponential backoff - Cache access tokens (don't generate new token for each request) - Batch operations when possible --- ## 6. Custom Fields ### 6.1 Text Custom Fields **Use case**: Store Salesforce record ID in envelope ```json { "compositeTemplates": [ { "inlineTemplates": [ { "customFields": { "textCustomFields": [ { "name": "SalesforceRecordId", "value": "0018V00000ABC123", "show": "false", "required": "false" } ] } } ] } ] } ``` ### 6.2 List Custom Fields ```json { "customFields": { "listCustomFields": [ { "name": "FormLanguage", "value": "English", "listItems": ["English", "Spanish"] } ] } } ``` --- ## 7. Webhook Configuration ### 7.1 Connect Webhook (for document retrieval) **Not required for Phase 1**, but useful for future automation. **Endpoint**: Configure in Docusign Admin → Connect → Add Configuration **Webhook payload** (when envelope completes): ```json { "event": "envelope-completed", "apiVersion": "v2.1", "uri": "/restapi/v2.1/accounts/123/envelopes/abc", "envelopeId": "f9876543-21ab-cdef-0123-456789abcdef", "envelopeSummary": { "status": "completed", "emailSubject": "Please review and sign", "completedDateTime": "2026-02-23T14:30:00Z" } } ``` --- ## 8. Template Management APIs ### 8.1 List Templates **Use case**: Retrieve template list for Flow dropdown **Request**: ```http GET /restapi/v2.1/accounts/{accountId}/templates?count=100&order=name&order_by=asc ``` **Response**: ```json { "resultSetSize": "14", "totalSetSize": "14", "envelopeTemplates": [ { "templateId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Form A - English", "shared": "true", "description": "English version of Form A" }, { "templateId": "b2c3d4e5-f6g7-8901-bcde-fg2345678901", "name": "Form B - English", "shared": "true", "description": "English version of Form B" } ] } ``` ### 8.2 Get Template Details **Use case**: Retrieve template metadata (recipients, tabs) **Request**: ```http GET /restapi/v2.1/accounts/{accountId}/templates/{templateId} ``` **Response**: ```json { "templateId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Form A - English", "recipients": { "signers": [ { "roleName": "Signer 1", "recipientId": "1", "routingOrder": "1" }, { "roleName": "Signer 2", "recipientId": "2", "routingOrder": "2" } ] }, "documents": [ { "documentId": "1", "name": "Form_A.pdf", "pages": "2" } ] } ``` --- ## 9. Apex HTTP Callout Example ### 9.1 Complete Callout ```apex public static String createCompositeEnvelope(String envelopeJSON, String accessToken, String accountId) { HttpRequest req = new HttpRequest(); req.setEndpoint('callout:DocusignAPI/accounts/' + accountId + '/envelopes'); req.setMethod('POST'); req.setHeader('Authorization', 'Bearer ' + accessToken); req.setHeader('Content-Type', 'application/json'); req.setHeader('Accept', 'application/json'); req.setBody(envelopeJSON); req.setTimeout(120000); // 120 seconds Http http = new Http(); HttpResponse res = http.send(req); if (res.getStatusCode() == 201) { Map responseMap = (Map) JSON.deserializeUntyped(res.getBody()); return (String) responseMap.get('envelopeId'); } else { throw new CalloutException('Docusign API error [' + res.getStatusCode() + ']: ' + res.getBody()); } } ``` ### 9.2 Named Credential Configuration **Setup → Named Credentials → New Named Credential** **Settings**: - **Label**: Docusign API - **Name**: DocusignAPI - **URL**: `https://na3.docusign.net/restapi/v2.1` - **Identity Type**: Named Principal - **Authentication Protocol**: OAuth 2.0 - **Scope**: `signature impersonation` - **Token Endpoint**: `https://account-d.docusign.com/oauth/token` (sandbox) - **JWT Token Exchange**: Enabled **Usage in Apex**: ```apex req.setEndpoint('callout:DocusignAPI/accounts/' + accountId + '/envelopes'); ``` --- ## 10. Testing with Postman ### 10.1 Import Docusign Collection Docusign provides an official Postman collection: https://github.com/docusign/postman-collections ### 10.2 Create Composite Envelope Test **Request**: ``` POST {{baseUrl}}/accounts/{{accountId}}/envelopes Headers: Authorization: Bearer {{accessToken}} Content-Type: application/json Body: { "status": "sent", "emailSubject": "Test Composite Envelope", "compositeTemplates": [ { "compositeTemplateId": "1", "serverTemplates": [ { "sequence": "1", "templateId": "{{templateId1}}" } ] }, { "compositeTemplateId": "2", "serverTemplates": [ { "sequence": "2", "templateId": "{{templateId2}}" } ] } ] } ``` --- ## 11. Reference Links - [Docusign REST API Reference](https://developers.docusign.com/docs/esign-rest-api/reference/) - [Composite Templates Guide](https://developers.docusign.com/docs/esign-rest-api/how-to/request-signature-composite-template/) - [JWT Authentication](https://developers.docusign.com/platform/auth/jwt/) - [Salesforce Named Credentials](https://help.salesforce.com/s/articleView?id=sf.named_credentials_about.htm) - [Salesforce HTTP Callouts](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_classes_restful_http_httprequest.htm) --- **Document Version**: 1.0 **Last Updated**: February 23, 2026