Idempotent Envelope Create API

---

title: Idempotent Envelope Create API

description: Run Idempotent Envelope Create API on Atlas with sequential signing, webhook events, and five free sends to validate staging.

date: 2026-06-25

updated: 2026-06-25

---

If you typed "idempotent envelope create api" into a search bar, you likely have a ticket to wire signing this sprint. Start with POST /api/envelope and finish with a webhook handler.

Share: One POST to create, one review click, one webhook when signed.

This guide walks through idempotent envelope create api on the Atlas REST API. PDF and DOCX are supported on every upload path.

Idempotency

Send Idempotency-Key on POST /api/envelope and POST /api/envelope/{id}/send. Atlas stores a hash keyed on your Idempotency-Key header for 24 hours. Retries with the same key return the original response instead of creating a second draft or consuming a second credit.

Multipart and JSON create paths namespace keys separately so the same string on both transports does not collide.

MCP write tools auto-stamp keys when the client omits them. REST callers should set explicit keys in production jobs.

Quick reference

Base URL: https://atlaswork.ai/api/. Singular /api/envelope for resource ops, plural /api/envelopes for list.

FAQ

Does Atlas support PDF and DOCX? Yes on every create path. DOCX converts to PDF at ingest.

How do I authenticate? Authorization: Bearer with an API key from dashboard settings. OAuth is for MCP connectors.

What does send cost? One credit per envelope dispatched. Five free credits on signup.

Can I skip review? REST supports auto_send: true on create or template send after legal approval. Default is review-first.

Where is the full API reference? /dev and /docs/guides/e-signature-api.

Next steps

Open /dev for OpenAPI detail. Sign up when you are ready to send.

Testing

Run one loop in staging: create with a two-page PDF, open review, send to a mailbox you control, sign on mobile, confirm webhook delivery. Use is_test: true in metadata when you want internal accounts skipped from Slack alerts.

Security

Store API keys server-side. Rotate keys from dashboard settings if leaked. Verify webhook signatures before updating production database rows.

Observability

Log envelope_id, fields_status, and webhook event types. When send fails, read metadata.send_error on the envelope row via GET /api/envelope/{id}.

Additional context for idempotent envelope create api

Atlas charges per send, not per seat. Detection and drafts are free. Multi-party envelopes sign sequentially. Each party receives a tokenized sign URL. Platform mode scopes child tenants with Atlas-Account. OpenAPI lives at /openapi.json. Agents can use MCP at /mcp while your backend uses REST for production traffic.

Send after review

When fields_status is ready, open review_url in a browser or call send from your backend:

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

Send consumes one credit. Drafts are free. Match fields_version from GET /api/envelope/{id} or receive 409 on conflict.

Poll status

Lightweight progress:

curl https://atlaswork.ai/api/envelope/{id}/status \
  -H "Authorization: Bearer $ATLAS_API_KEY"

Returns status, signed_count, total, and next_signer_email. Prefer webhooks in production.

Sequential signing

Multi-party envelopes sign in order. Each sign_url includes ?t=<token>. Fields filter server-side per party. See Sequential signing.

Field detection

Upload triggers async detection on PDF or DOCX. Poll until fields_status is not pending. Manual placement fallback when status is recovered_empty. Guide: Field detection.

Templates

Repeat sends use POST /api/templates/{id}/send. Do not pass template_id to envelope create (returns 400).

Platform mode

Multi-tenant SaaS can provision POST /api/platform/connected-accounts and scope with Atlas-Account: ext_<id>. See /platforms.

Credits and billing

Five free credits on signup. One credit per send. 402 when exhausted. Purchase more in dashboard billing. No seat minimums.

MCP parity

Agents use MCP at /mcp. Production backends typically use REST. Both share envelope rows.

Security checklist

Store API keys server-side only. Verify webhook HMAC before updating database rows. Rotate keys from dashboard settings if leaked.

Troubleshooting

409 on send while fields_status is pending means detection still running. 409 on version mismatch means refresh fields_version. Log envelope_id on every create for support traces.

Webhook events

Set webhook_url at create. Atlas POSTs JSON with X-Atlas-Signature: sha256=.... Verify HMAC with your API key.

Event	When
`envelope.sent`	Email dispatched to first signer
`envelope.signed`	All parties finished
`envelope.declined`	A signer declined
`envelope.voided`	Sender voided pending envelope
`contract.extracted`	Post-sign structured extract ready

See platform webhooks.

Void and remind

Cancel pending work:

curl -X POST https://atlaswork.ai/api/envelope/{id}/void \
  -H "Authorization: Bearer $ATLAS_API_KEY"

Nudge the next signer:

curl -X POST https://atlaswork.ai/api/envelope/{id}/remind \
  -H "Authorization: Bearer $ATLAS_API_KEY"

Download signed PDF

When status is signed, GET /api/envelope/{id} returns signed download URLs if the artifact is archived.

OpenAPI reference

Interactive docs: /dev. Machine-readable: /openapi.json. Agent instructions: /llms.txt.

Getting started checklist

Sign up and copy an API key.
Run create with Idempotency-Key.
Poll fields_status or watch review UI.
Send after review.
Wire webhooks before production traffic.

API reference

Full route list and request schemas live at /dev. Start with E-signature API for the mental model, then use this guide for copy-paste examples.