REST vs GraphQL for e-sign APIs

GraphQL fans ask for one query that returns envelope, parties, fields, and audit events in a single round trip. E-sign vendors mostly ship REST anyway. The question is whether that matters for your integration.

Atlas exposes REST with OpenAPI at /dev. There is no GraphQL endpoint today. This page explains why REST still wins most signing stacks and when you would reach for GraphQL elsewhere.

> Share: "Signing is action-heavy. REST maps cleanly to send, sign, void, and webhook."

How signing APIs behave

E-sign integrations are not read-mostly product catalogs. They are state machines with side effects:

• Create uploads bytes and starts detection
• Send consumes credits and emails signers
• Submit signature mutates party status and may generate PDFs
• Webhooks push async events to your server

REST maps each action to a verb and route. That matches how lawyers talk about the workflow: "create the envelope," "send it," "void it."

GraphQL shines when mobile clients need flexible reads across nested graphs with minimal over-fetching. Signing dashboards could use that. Headless agent flows usually do not.

Atlas REST surface

Multipart create handles PDF or DOCX upload. JSON create handles base64 or document_url. Same lifecycle after create.

MCP tools wrap the same backend for Claude and ChatGPT. Transport differs. State does not.

Polling vs subscriptions

GraphQL subscriptions could stream fields_status and party updates. Atlas clients poll GET /api/envelope/{id} or use webhooks for envelope.signed.

Polling is fine when detection takes seconds and humans gate send on review anyway. Webhooks cover backend sync when the chat thread ends.

If you need sub-second UI on a custom signing portal, wrap Atlas REST in your own GraphQL BFF. That layer can coalesce reads without waiting for Atlas to ship GraphQL natively.

Idempotency and writes

Create and send paths accept idempotency keys on REST. Retries from Zapier, n8n, or agent loops must not duplicate envelopes.

GraphQL mutations can carry idempotency too, but tooling maturity in e-sign is thinner. Most migration guides assume curl and OpenAPI codegen.

Developer ergonomics

OpenAPI generates clients in TypeScript, Python, and Go. Postman collections and MCP tool schemas already target REST shapes.

GraphQL would add schema stitching for file uploads, binary PDF downloads, and HMAC webhook verification docs that do not fit a graph resolver model cleanly.

When GraphQL e-sign might appear

Marketplaces that bundle CRM, billing, and signing in one mobile app sometimes expose GraphQL for dashboard reads. Pure API buyers automating NDAs from GitHub Actions rarely ask for it.

If your requirement is "GraphQL only," Atlas is not a fit today. If your requirement is "POST envelope from code with webhooks," REST is the path.

Honest comparison

Migration note

Teams arriving from GraphQL-only internal platforms can keep GraphQL at the edge. Map mutations to Atlas REST routes one to one. Do not block shipping on waiting for vendor GraphQL.

Treat file upload as a separate REST multipart call, not a nested GraphQL field. Signed PDF download stays a binary GET. Those two steps rarely benefit from graph nesting anyway. Keep them explicit in runbooks.

Pilot checklist

1. Create test envelope with PDF via curl
2. Poll until fields ready
3. Open review_url and send
4. Verify webhook signature handling
5. Download signed PDF artifact for legal

That exercise tells you more than schema introspection about fit.

Common mistakes

Teams new to rest vs graphql esign often send before field detection finishes. Wait until fields_status is ready. If you hit 409, open review_url and read the banner.

Another miss: sharing a bare /sign/{id} link on multi-party deals. Each signer needs their token in the URL so they only see their fields.

Do not store API keys in frontend code or public chat logs. Create envelopes from a server you control.

Staging checklist

Run one envelope to your own email before production traffic. Confirm webhook delivery, signed PDF download, and credit decrement match what finance expects.

Log create responses in structured JSON. When a signer says they never got email, envelope ID finds the row faster than subject search.

If you use agents, document three approved prompts: create send, check status, remind signer. Wild prompts in live deal threads cause wrong-party sends.

Team rollout

Run a 30-minute internal demo: connect your stack, send a test PDF or DOCX to yourself, sign on phone, show the webhook in staging. Record the screen for async teammates.

Publish a one-page internal FAQ after vendor pick so Slack stops re-debating the same question every quarter.

Metrics that matter

Track median hours from verbal agreement to signed PDF. That number convinces finance faster than feature grids.

Track webhook delivery latency at p95. Slow hooks mean CRM lies about deal stage.

Track support tickets per hundred sends in month one. Spikes usually mean review training gaps, not API bugs.

Pilot workflow

Week one: one document type, internal signers only, webhook wired to staging. Week two: one external signer with real terms. Compare signed PDF output with counsel before you widen scope.

Keep a shared spreadsheet of envelope IDs during pilot. Note create time, send time, first open, and signed time.

If agents create envelopes, require review on every new template version. Auto-send is a reward for proven shapes, not day-one default.

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.

Related reading

• Documentation
• E-signature API guide
• MCP electronic signatures