What is a DocuSign envelope?
DocuSign envelope definition, lifecycle states, how documents and recipients fit inside one envelope, and the Atlas envelope model for developers.
Shaan F.
Co-founder & CEO, Atlas
On this page
In DocuSign, an envelope is the container for one signing transaction. It holds documents, recipients (signers), tabs/fields, routing order, reminders, and status. Billing often counts one envelope per transaction sent, regardless of how many PDFs sit inside.
Understanding envelopes is prerequisite to reading DocuSign API docs or comparing migration cost to Atlas.
> Share: "A DocuSign envelope is one send unit: documents plus signers plus workflow."
Envelope contents
Typical envelope includes:
- Documents: one or more PDFs (converted from Word upstream)
- Recipients: signers, carbon copies, witnesses depending on plan
- Fields: signature, initial, date, text tabs placed on pages
- Workflow: sequential or parallel routing (Atlas uses sequential only)
- Metadata: subject, email blurb, custom fields
Templates are saved envelope definitions without hitting Send yet.
Lifecycle states
DocuSign envelope status progresses roughly:
- Created / draft: not sent
- Sent / delivered: signers notified
- Completed: all required signatures captured
- Declined / voided: terminal failure states
Atlas uses draft, pending, signed, declined, voided, and expired with DB-derived status. See DocuSign Envelope API map for side-by-side mapping.
One envelope vs many documents
Multiple PDFs in one envelope suit packet signing (policy plus acknowledgment). Separate envelopes suit unrelated contracts even if signers overlap.
Mis-splitting envelopes breaks audit grouping. Over-merging sends unrelated docs in one email thread.
Envelope ID in integrations
Every API call references envelopeId. Webhooks emit events with that ID. CRM integrations store it on opportunities.
Migration requires mapping old envelope IDs in archive to new vendor IDs going forward. Historical search stays on DocuSign until export finishes.
Atlas envelope model
Atlas POST /api/envelope creates a draft with uploaded PDF or DOCX. Response includes envelope_id and review_url. Send promotes parties to pending and consumes one credit.
curl -X POST https://atlaswork.ai/api/envelope \
-H "Authorization: Bearer $ATLAS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"document_url":"https://example.com/nda.pdf"}'
MCP tools get_envelope and check_signing_status wrap the same resource.
Common beginner mistakes
| Mistake | Consequence |
|---|---|
| Sending before fields placed | Signers blocked or sign wrong page |
| Reusing envelope after complete | Must create new envelope |
| Ignoring envelope ID in webhooks | CRM desync |
Envelope naming conventions
Consistent subject lines help support search. Pattern like {OpportunityId} - MSA - {AccountName} beats "Please sign". Custom fields store CRM keys for API queries later.
Voided envelopes should include reason code in internal notes for quarterly ops review.
Plural reporting view: DocuSign envelopes.
Operational checklist before you scale
Document the owner for template changes, integration credentials, and signer support escalation. Run a thirty-minute tabletop exercise: candidate cannot open link, finance needs certificate today, API returns 429 during launch. Write answers in internal wiki with envelope ID examples redacted.
Measure time-to-first-completed-envelope for new hires on ops team. If only one person knows admin console, bus factor is high. Export sandbox walkthrough recording when vendor UI updates each quarter.
For hybrid stacks, label outbound emails so signers know which brand hosts their session. Mixed DocuSign and Atlas emails confuse recipients and increase phishing reports to IT.
When migrating vendors, keep legacy read-only login until archive export finishes. Do not cancel production keys until webhook consumers handle new event schema in staging.
Review credit or envelope burn monthly against forecast. Spiky nonprofits and seasonal bulk sends surprise finance if unmonitored.
Train agents and support to request envelope ID first. Guessing from subject line wastes cycles.
Align legal retention on signed PDF plus audit artifacts with IT backup policy. Cloud vendor retention defaults may be shorter than regulatory need.
If signers routinely complete on mobile, test mobile browser on both iOS Safari and Android Chrome before policy mandates ID verification.
Publish internal SLA for signature turnaround separate from vendor uptime SLA. Business expectation management reduces escalations to engineering.
Schedule semiannual access review for admin accounts on signing platform. Former contractors with send permission are a common audit finding.
FAQ
Does Atlas accept PDF and DOCX?
Yes. Upload either format when you create an envelope. DOCX files become PDF before anyone signs.
How do I sign in?
Use a Bearer API key from your dashboard settings. MCP connectors in ChatGPT and Claude use OAuth instead.
When do credits get used?
One credit per send, not per upload. You get five free sends when you sign up.
Where should I start?
/docs and API reference.