API Specification
A REST API for programmatic signing. Built for agents that prepare and route, and for enterprises that need evidence-grade audit trails and domain control.
Bearer tokens. Least-privilege scopes.
Every request carries a scoped API key in the Authorization header. Keys are prefixed for identification and carry a visible last-used timestamp.
curl https://api.sumosign.com/v1/envelopes \
-H "Authorization: Bearer sk_live_********" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"name": "MSA — Acme & Northwind",
"document_id": "doc_01HXY...",
"routing_mode": "sequential",
"recipients": [
{ "email": "ops@acme.com", "name": "A. Ops", "routing_order": 1 }
],
"webhook_url": "https://acme.com/hooks/sumosign"
}'All mutating requests support idempotency keys.
What an agent needs to prepare, route, and close.
These capabilities form the minimum API surface for autonomous signing workflows. Every feature is exposed through scoped credentials with the same audit rigor as dashboard actions.
Envelope lifecycle
Create, configure, send, void, and poll envelopes. Sequential and parallel routing. Expiration and reminder policies.
Template instantiation
Define reusable templates with pre-placed fields. Agents instantiate them in a single call, filling only the variable fields.
Recipient management
Add, update, reorder, and remove signers before sending. Reminders and replacement tokens for bounced or wrong addresses.
Scoped machine credentials
Create API keys with granular scopes. Rotate without breaking active flows. Audit who acted under which credential.
Event-driven orchestration
Subscribe to envelope lifecycle events. HMAC-signed payloads with idempotent event IDs. Retry with backoff.
Idempotent mutations
All mutating endpoints accept idempotency keys. Safe to retry on timeout or network failure without duplicate side effects.
Status polling
Poll envelope and recipient status at any time. Filter lists by status, date range, and metadata tags.
Evidence retrieval
Fetch structured audit trails, certificates of completion, and signed document downloads as soon as an envelope completes.
What a regulated team demands before deployment.
These features address procurement, compliance, and security review. Available features ship today. Planned features are on the public roadmap.
Custom signing domains
Host signing pages on sign.yourcompany.com. TLS, DNS, and security policy under your control.
Organization-scoped resources
Multi-tenant resource isolation. Every read and write is automatically scoped to the authenticated organization.
Role-based access control
Least-privilege roles: Owner, Admin, Operator, Viewer. Scoped API keys inherit the creator's role boundaries.
Data residency
Choose the region where envelope data, documents, and audit trails are stored and processed.
SSO / SAML
Authenticate dashboard users through your identity provider. JIT provisioning and session enforcement.
Compliance exports
Bulk export audit trails, certificates, and evidence bundles in formats suited for SOC 2, legal discovery, and regulatory review.
Bulk operations
Send, void, or archive envelopes in batches. Asynchronous job status with progress polling.
Advanced branding
Full white-label control over signing pages, email templates, and certificate styling.
Predictable JSON. HATEOAS links.
Resources include id, status, timestamps, and a links object for related navigation. Errors follow RFC 7807 Problem Details.
{
"id": "env_9f3k2m...",
"status": "sent",
"name": "MSA — Acme & Northwind",
"routing_mode": "sequential",
"document_ids": ["doc_01HXY..."],
"recipient_ids": ["rcp_4a9b..."],
"metadata": { "crm_deal_id": "deal_4821" },
"webhook_url": "https://acme.com/hooks/sumosign",
"idempotency_key": "7b9c2c3a-...",
"created_at": "2025-06-12T09:23:17Z",
"sent_at": "2025-06-12T09:23:18Z",
"completed_at": null,
"expires_at": "2025-07-12T09:23:17Z",
"links": {
"self": "/v1/envelopes/env_9f3k2m...",
"documents": "/v1/envelopes/env_9f3k2m.../documents",
"recipients": "/v1/envelopes/env_9f3k2m.../recipients",
"audit": "/v1/envelopes/env_9f3k2m.../audit",
"certificate": "/v1/envelopes/env_9f3k2m.../certificate"
}
}Endpoints
Six resource groups. All paths are prefixed with https://api.sumosign.com.
Envelopes
Create, send, and manage signing packets.
/v1/envelopes/v1/envelopes/{id}/v1/envelopes/v1/envelopes/{id}/send/v1/envelopes/{id}/void/v1/envelopes/{id}/audit/v1/envelopes/{id}/certificateDocuments
Upload, hash-verify, and retrieve signed PDFs.
/v1/documents/v1/documents/{id}/v1/documents/{id}/download/v1/documents/{id}Recipients
Manage signers and viewers on an envelope.
/v1/envelopes/{id}/recipients/v1/envelopes/{id}/recipients/{rid}/v1/envelopes/{id}/recipients/{rid}/remind/v1/envelopes/{id}/recipients/{rid}Templates
Reusable document configurations with pre-placed fields.
/v1/templates/v1/templates/v1/templates/{id}/v1/templates/{id}/instantiate/v1/templates/{id}Fields
Place signature, date, text, and checkbox fields.
/v1/envelopes/{id}/fields/v1/envelopes/{id}/fields/v1/envelopes/{id}/fields/{fid}/v1/envelopes/{id}/fields/{fid}Webhooks
Subscribe to envelope lifecycle events.
/v1/webhooks/v1/webhooks/v1/webhooks/{id}/rotate-secret/v1/webhooks/{id}HMAC-signed event deliveries.
Subscribe to envelope events and receive structured payloads at your URL. Failed deliveries retry with exponential backoff. Every attempt is logged.
X-SumoSign-Signature header.event_id for deduplication.{
"event_id": "evt_8k2m9p...",
"type": "envelope.completed",
"created_at": "2025-06-12T14:33:02Z",
"data": {
"envelope_id": "env_9f3k2m...",
"status": "completed",
"completed_at": "2025-06-12T14:33:01Z",
"certificate_url": "/v1/envelopes/env_9f3k2m.../certificate"
}
}Use the REST API today.
The REST API is fully usable from any HTTP client today. Typed SDKs and an OpenAPI spec are in active development.
Build signing into your product.
Request an API key and start building. Tell us what you would build first.