'delivered' means the email was opened, not that the document was signed
'completed' means all recipients have signed
Recipients array shows individual signing status per recipient
Envelope IDs are GUIDs; always resolve from creation or search results
4. Add Templates to Existing Envelopes
When to use
User wants to add additional documents or templates to an existing envelope
Tool sequence
:
DOCUSIGN_GET_ENVELOPE
- Verify envelope exists and is in draft state [Prerequisite]
DOCUSIGN_ADD_TEMPLATES_TO_DOCUMENT_IN_ENVELOPE
- Add template to envelope [Required]
Key parameters
:
envelopeId
Target envelope ID
documentId
Document ID within the envelope
templateId
Template to add
Pitfalls
:
Envelope must be in 'created' (draft) status to add templates
Cannot add templates to already-sent envelopes
Document IDs are sequential within an envelope (starting from '1')
Adding a template merges its fields and roles into the existing envelope
5. Manage Envelope Lifecycle
When to use
User wants to send, void, or manage draft envelopes
Tool sequence
:
DOCUSIGN_GET_ENVELOPE
- Check current envelope status [Prerequisite]
DOCUSIGN_SEND_ENVELOPE
- Send a draft envelope [Optional]
Key parameters
:
envelopeId
Envelope to manage
For sending: envelope must be in 'created' status with all required recipients
Pitfalls
:
Only 'created' (draft) envelopes can be sent
Sent envelopes cannot be unsent; they can only be voided
Voiding an envelope notifies all recipients
All required recipients must have valid email addresses before sending
Common Patterns
ID Resolution
Template name -> Template ID
:
1. Call DOCUSIGN_LIST_ALL_TEMPLATES
2. Find template by name in results
3. Extract templateId (GUID format)
Envelope tracking
:
1. Store envelopeId from CREATE_ENVELOPE_FROM_TEMPLATE response
2. Call DOCUSIGN_GET_ENVELOPE periodically to check status
3. Check recipient-level status for individual signing progress
Template Role Mapping
When creating an envelope from a template:
1. Call DOCUSIGN_GET_TEMPLATE to see defined roles
2. Map each role to actual recipients:
{
"roleName": "Signer 1", // Must match template role name exactly
"name": "John Smith",
"email": "john@example.com"
}
3. Include ALL required roles in templateRoles array
Envelope Status Flow
created (draft) -> sent -> delivered -> signed -> completed
-> declined
-> voided (by sender)
Known Pitfalls
Template Roles
:
Role names are case-sensitive; must match template definition exactly
All required roles must be assigned when creating an envelope
Missing role assignments cause envelope creation to fail
Envelope Status
:
'delivered' means email opened, NOT document signed
'completed' is the final successful state (all parties signed)
Status transitions are one-way; cannot revert to previous states
GUIDs
:
All DocuSign IDs (templates, envelopes) are GUID format
Always resolve names to GUIDs via list/search endpoints
Do not hardcode GUIDs; they are unique per account
Rate Limits
:
DocuSign API has per-account rate limits
Bulk envelope creation should be throttled
Polling envelope status should use reasonable intervals (30-60 seconds)
Response Parsing
:
Response data may be nested under
data
key
Recipient information is nested within envelope response
Date fields use ISO 8601 format
Parse defensively with fallbacks for optional fields
Quick Reference
Task
Tool Slug
Key Params
List templates
DOCUSIGN_LIST_ALL_TEMPLATES
(optional filters)
Get template
DOCUSIGN_GET_TEMPLATE
templateId
Create envelope
DOCUSIGN_CREATE_ENVELOPE_FROM_TEMPLATE
templateId, templateRoles, status
Send envelope
DOCUSIGN_SEND_ENVELOPE
envelopeId
Get envelope status
DOCUSIGN_GET_ENVELOPE
envelopeId
Add template to envelope
DOCUSIGN_ADD_TEMPLATES_TO_DOCUMENT_IN_ENVELOPE
envelopeId, documentId, templateId
Powered by
Composio