DocuSign create envelope API

The DocuSign create envelope API is the first call in almost every integration. Searchers want POST /envelopes payload shape, draft versus sent status, and how documents attach before recipients sign.

DocuSign create envelope API (REST)

Base path (demo example):

POST /restapi/v2.1/accounts/{accountId}/envelopes

Required pieces:

• Authorization: Bearer OAuth access token tied to a DocuSign user (seat licensing implications)
• documents: array with documentBase64 or document from template
• recipients.signers: email, name, recipientId, routingOrder
• status: created for draft or sent to dispatch immediately

Minimal JSON create:

curl -X POST "https://demo.docusign.net/restapi/v2.1/accounts/$ACCOUNT_ID/envelopes" \
  -H "Authorization: Bearer $DS_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "emailSubject": "Please sign",
    "status": "created",
    "documents": [{
      "documentId": "1",
      "name": "contract.pdf",
      "documentBase64": "JVBERi0x..."
    }],
    "recipients": {
      "signers": [{
        "email": "signer@example.com",
        "name": "Signer",
        "recipientId": "1",
        "routingOrder": "1",
        "tabs": {
          "signHereTabs": [{ "documentId": "1", "pageNumber": "1", "xPosition": "100", "yPosition": "200" }]
        }
      }]
    }
  }'

Response includes envelopeId used on all follow-up routes.

Send draft:

PUT /accounts/{accountId}/envelopes/{envelopeId} with "status": "sent"

Common create envelope API mistakes

Missing tabs. Create succeeds but signers see blank pages. Atlas avoids manual tab arrays with detection plus review UI.

Wrong accountId. Sandbox and production IDs differ. CI pointing at prod breaks limits quickly. See DocuSign API limits.

Immediate sent in CI. Tests consume send quota. Prefer created status in sandboxes when possible.

Base64 size limits. Large PDFs need chunked upload or alternative document sources.

Atlas create envelope equivalent

Atlas splits create and send for review-first workflows.

POST /api/envelope accepts PDF or DOCX via JSON (document_url, document base64) or multipart file upload.

curl -X POST https://atlaswork.ai/api/envelope \
  -H "Authorization: Bearer $ATLAS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-nda-42" \
  -d '{
    "document_url": "https://example.com/nda.pdf",
    "parties": [{ "email": "signer@example.com", "name": "Signer", "role": "Customer" }]
  }'

Returns envelope_id and review_url. Send is separate POST /api/envelope/{id}/send after fields_status is ready.

Map mentally: DocuSign create+sent in one call ≈ Atlas create → review → send (two steps, human gate on ad hoc).

Route map (create-focused)

Full lifecycle table below covers status, void, remind.

DocuSign Envelope API (full lifecycle)

The DocuSign Envelope API is the core REST surface for create, send, status, and download. Teams migrating to Atlas need a route-by-route map, not a feature checklist.

DocuSign envelope lifecycle (API view)

Typical DocuSign flow:

1. POST /envelopes with documents, recipients, tabs
2. Optional draft status, then PUT to send
3. Connect webhooks or GET status for updates
4. GET documents combined for signed PDF

DocuSign uses OAuth, accountId, and envelopeId in most paths. Tabs are often placed manually in API payloads or templates.

Atlas lifecycle map

Create comparison

DocuSign (simplified):

curl -X POST "https://demo.docusign.net/restapi/v2.1/accounts/$ACCOUNT_ID/envelopes" \
  -H "Authorization: Bearer $DS_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "sent",
    "documents": [{ "documentId": "1", "name": "nda.pdf", "documentBase64": "..." }],
    "recipients": {
      "signers": [{ "email": "signer@example.com", "name": "Signer", "recipientId": "1", "routingOrder": "1" }]
    }
  }'

Atlas (review-first default):

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",
    "parties": [{ "email": "signer@example.com", "name": "Signer", "role": "Customer" }]
  }'

Atlas returns review_url. After human approval:

curl -X POST "https://atlaswork.ai/api/envelope/$ENVELOPE_ID/send" \
  -H "Authorization: Bearer $ATLAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"parties":[{"email":"signer@example.com","name":"Signer","role":"Customer"}]}'

Webhooks

DocuSign Connect delivers XML or JSON with configurable triggers. Atlas sends JSON with HMAC signature header.

Map common events:

• envelope-sent → envelope.sent
• recipient-completed / completed → envelope.signed (when all parties done)
• voided → envelope.voided
• declined → envelope.declined

Idempotency

Both systems benefit from idempotent creates and sends. Atlas supports Idempotency-Key header on POST /api/envelope and send routes (24-hour dedupe window).

Field placement migration

DocuSign integrations often hardcode tab coordinates. Atlas runs AI-assisted field detection, then humans confirm in review. Budget UX time for ops to trust detection on your document set before removing manual tab arrays.

Re-detect: POST /api/envelope/{id}/redetect when document changes.

MCP alternative for agents

Agent clients can skip raw REST with MCP tools:

• send_contract_for_review
• check_signing_status
• get_envelope

See MCP electronic signatures.

When to keep DocuSign Envelope API

• Templates and Connect integrations are embedded in dozens of services.
• You rely on DocuSign-specific recipient authentication options Atlas does not mirror.
• Legal blocked parallel vendors until a full migration plan is approved.

Further reading

• E-signature API guide
• Signature API
• Sequential signing
• DocuSign CLM API guide
• DocuSign API limits

Envelope API FAQ

Does Atlas use tab arrays? No. Detection proposes fields; review confirms. DocuSign tabs are often explicit in API payloads.

Embedded signing? Atlas sign pages are hosted at atlaswork.ai/sign. Embedded patterns use your portal linking to sign URLs with party tokens.

Bulk send? DocuSign bulk jobs map to Atlas template bulk or repeated POST /api/templates/{id}/send. See template docs.

Recipient authentication? Compare DocuSign SMS/KBA options to your compliance needs. Atlas supports sequential signing with email links and optional OTP paths on sign routes.

Idempotency on resend? Atlas send is idempotent against double-charge when envelope already pending. Use Idempotency-Key header on create and send.