Hellosign API
---
title: Hellosign API
description: Developer Hellosign API on Atlas: OpenAPI-aligned routes, MCP parity, and five free sends on signup. Includes five free sends on signup.
date: 2026-06-25
updated: 2026-06-25
---
If you typed "hellosign 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.
Atlas quick start
Authenticate with Authorization: Bearer <api_key>. Create accepts PDF or DOCX on JSON or multipart transports.
curl -X POST https://atlaswork.ai/api/envelope \
-H "Authorization: Bearer $ATLAS_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: hellosign-api-demo-1" \
-d '{
"document_url": "https://example.com/agreement.pdf",
"parties": [{"email": "signer@example.com", "name": "Signer", "role": "Customer"}]
}'
Response includes envelope_id and review_url. Field detection runs async. Poll GET /api/envelope/{id} until fields_status is ready, failed, or recovered_empty.
Send after review:
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"}], "fields_version": 1}'
One credit consumes at send. Drafts and detection are free. Full reference: e-signature API.
Mapping from Hellosign
| Hellosign concept | Atlas equivalent |
|---|---|
| Create envelope | POST /api/envelope |
| Send / dispatch | POST /api/envelope/{id}/send |
| Recipient / signer | parties[] with email, name, role |
| Tabs / fields | Detected fields + review UI |
| Connect webhook | webhook_url + X-Atlas-Signature HMAC |
See Hellosign comparison for pricing context.
Error handling
402 when credits exhausted. 409 on fields_version mismatch or send while detection pending. 400 on malformed parties.
Log envelope_id on every create for support traces.
Testing checklist
- Create with two-page PDF
- Open review_url, confirm fields
- Send to mailbox you control
- Sign on mobile
- Verify webhook and signed PDF download
Sign up for five free sends.
Implementation depth for "hellosign api"
Production signing integrations fail on edge cases, not happy-path demos. Below is a checklist teams wish they had before the first production send.
Create path hardening
Always pass Idempotency-Key on POST /api/envelope. Retries from Zapier, n8n, or your job runner must not spawn duplicate envelopes.
Upload PDF or DOCX via multipart when bytes live on disk. Use document_url when the file already sits on S3 or your object storage.
Poll fields_status before send. Sending while detection is pending returns 409.
Review gate semantics
Atlas defaults to review-first on ad-hoc creates. Your agent or API uploads the file; a human opens review_url, confirms detected fields and parties, then clicks Send.
That gate prevents misaddressed contracts without building a custom approval service. Templates can auto-send once legal trusts the shape.
If you need immediate dispatch from server code only, pass auto_send: true at create on REST. MCP tools always return review links for new uploads.
Webhook verification
Set webhook_url at create. Verify X-Atlas-Signature HMAC with your API key before you mutate CRM or billing state.
Handle at least: envelope.sent, envelope.signed, envelope.voided, envelope.declined, and contract.extracted if you use post-sign extraction.
Treat duplicate webhook delivery as idempotent using envelope_id plus event type as a natural key.
Sequential signing rules
Atlas signs in order. Party 1 receives email first. Party 2 waits until party 1 finishes.
Multi-party sign URLs must include ?t=<token> so each signer only sees their fields. Never share a bare /sign/{id} link on multi-party envelopes.
API surface map
| Action | Atlas route |
|---|---|
| Create | POST /api/envelope |
| Read | GET /api/envelope/{id} |
| Send | POST /api/envelope/{id}/send |
| Void | POST /api/envelope/{id}/void |
| Remind | POST /api/envelope/{id}/remind |
| Template send | POST /api/templates/{id}/send |
OpenAPI: /openapi.json. Agent instructions: /llms.txt.
MCP parity
Ten MCP tools mirror the lifecycle: create, template send, get, status, list, void, remind, extract, and more.
Connect at /mcp/claude or /mcp/chatgpt when the caller is an agent rather than your backend.
Agents should not hold long-lived user OAuth tokens for incumbents when MCP discovery handles auth.
Error codes you will hit
402 when credits exhausted at send time. Buy envelopes at /dashboard/billing or upgrade before peak season.
409 when fields_version or parties_version mismatch, or when send runs while fields_status is still pending.
400 when required parties missing on send or malformed JSON on create.
Stakeholder alignment
Legal cares about audit trail export. Finance cares about seat true-up. Engineering cares about sandbox uptime and API stability.
Agents introduce a fourth stakeholder: platform team cares about MCP, OAuth, and whether send requires human review by default.
Run a 30-minute workshop with each group before vendor selection. Publish internal FAQ after decision to stop repeated Slack debates.
Pilot success metrics
Time from upload to first signed PDF on a test envelope.
Webhook delivery latency p95 under load.
Support tickets per hundred sends in the first month.
Cost per signed document at peak volume including admin seat overhead.
Searching hellosign api? Pick a metric above and test it on Atlas with five free sends at /signup.
FAQ
Does Atlas support PDF and DOCX? Yes on every create path.
Can agents call this API? Yes via MCP or REST. See /mcp.
Where is OpenAPI? /openapi.json and /llms.txt.