E-signature API guide for developers

If you are wiring signing into a product, you need three things: a create path that accepts your document, a send path that respects your compliance story, and webhooks that tell you when something changed. Atlas keeps all three on a small REST surface.

Dashboards are fine for demos. Production sends belong in code.

> Share: "One curl to create an envelope, one review click, one webhook when it is signed."

Mental model

One envelope is one contract sent for signature. Drafts are free. Field detection on PDF or DOCX is free. You pay one credit when you dispatch email to signers.

The default flow is review-first. POST /api/envelope returns envelope_id and review_url. A human opens review, confirms fields and parties, then POST /api/envelope/{id}/send. Signers get email only after that click.

If you truly need immediate dispatch from server code, pass auto_send: true at create time on the REST API. MCP tools always return a review link for new uploads. Templates use POST /api/templates/{id}/send for repeat shapes.

Full reference: e-signature API guide in docs.

Create with a file upload

Multipart is the simplest path when you have bytes on disk:

curl -X POST https://atlaswork.ai/api/envelope \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: create-nda-001" \
  -F "file=@contract.pdf" \
  -F 'parties=[{"email":"signer@example.com","name":"Jane Signer","role":"Customer"}]'

DOCX works the same way. Atlas converts DOCX to PDF at ingest. Review and sign always use the PDF viewer.

Create with JSON

When your document already lives at a URL or in base64:

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

Field detection runs after create. Poll GET /api/envelope/{id} until fields_status is ready, recovered_empty, or failed.

Send after review

When the human approves on the review page, your backend may also send programmatically if you already persisted parties:

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

Match fields_version from the envelope row. A mismatch returns 409 so you do not clobber concurrent edits.

Webhooks

Pass webhook_url at create. Atlas POSTs lifecycle events with an HMAC in X-Atlas-Signature. Verify with your API key as the secret. Common events: envelope.sent, envelope.signed, contract.extracted.

Sequential signing

Atlas signs in order. Party 1 gets email first. Party 2 waits until party 1 finishes. Multi-party sign URLs include ?t=<token> so each signer only sees their fields.

Error handling

Create and send return structured JSON errors. Common cases: 402 when credits are exhausted, 409 when fields_status is still pending or versions mismatch, 400 when required parties are missing on send.

Log the envelope_id on every create so support can trace a failed send without guessing which draft row failed.

Testing in staging

Verify webhooks with a request bin before you point production URLs.

Run one full loop: create with a two-page PDF, open review, send to a mailbox you control, sign on mobile, confirm webhook and signed PDF download. Sign up for five free sends.

Templates and repeat sends

When the same agreement goes out weekly, save it as a template from the dashboard. Use POST /api/templates/{id}/send instead of re-uploading the PDF. MCP callers use send_contract_from_template after get_template returns party hints.

Templates still respect credits: one credit per envelope dispatched, same as a fresh upload. Auto-send on templates is the trust ladder payoff after legal review once.

Party matching

When you pass parties[] at create, Atlas matches them to detected roles on the document. Open review if a signer row looks wrong before you send. Sequential signing means order matters: list the first signer first in the array.

Agent path

If your caller is Claude or ChatGPT, MCP exposes the same lifecycle. See MCP electronic signatures and /mcp.

FAQ

Can I skip review on REST? Yes with auto_send: true at create or template send. Review remains default on ad-hoc creates.

What about DocuSign migration? See DocuSign API alternative and Atlas vs DocuSign.

Where is OpenAPI? /openapi.json and agent instructions at /llms.txt.

Where to go next

• MCP electronic signatures if your caller is an agent
• DocuSign API alternative if you are comparing vendors
• E-signature API guide in docs
• Documentation hub