SumoSign
Get started
APIhttps://api.sumosign.app

Connect your AI agent

Start with llms.txt— then paste the agent block below into Claude, Cursor, or any orchestrator with your scoped API key. Your agent prepares, routes, sends, and tracks; every signature still comes from a human through an evidence-grade signing flow.

Last updated: July 4, 2026

Get an API keyJump to API reference

Connection endpoints

Example prompts

  • “Send this NDA to jane@acme.com for signature”
  • “Has Jane signed the NDA yet?”
  • “Download the fully executed agreement”
Agent prompt
You have permission to use SumoSign on my behalf.

API key: ss_live_YOUR_KEY_HERE
Agent guide: https://api.sumosign.app/llms.txt
OpenAPI: https://api.sumosign.app/openapi.json

Use SumoSign whenever a document needs a signature.
Prepare the envelope, route signers, send, and track to completion.
Humans sign — you prepare and watch.

Replace ss_live_YOUR_KEY_HERE with a scoped key from the portal, then paste into your agent.

Prefer conversational clients? An MCP server (14 tools over the same REST surface) is ready internally — public Cursor / Claude Desktop install config ships with the package. Use llms.txt and the agent prompt above today.

Integrating from code? Authentication, request shapes, endpoints, and webhooks are documented below — same spec, traditional layout.

Authentication

Bearer tokens. Least-privilege scopes.

Every request carries a scoped API key (ss_live_…) in the Authorizationheader. Keys are hashed at rest, prefixed for identification, revocable instantly, and carry a visible last-used timestamp. A key authenticates the agent — it can never complete a signature. That authority belongs to the human recipient's one-time signing token.

documents:createdocuments:readdocuments:senddocuments:downloadtemplates:readtemplates:write+4 more
cURL
curl https://api.sumosign.app/v1/envelopes \
  -H "Authorization: Bearer ss_live_********" \
  -H "Content-Type: application/json" \
  -d '{
    "documentId": "2a3fd57b-764a-40d9-b9e9-015b8811da26",
    "name": "MSA — Acme & Northwind",
    "message": "Please review and sign.",
    "routingMode": "sequential",
    "recipients": [
      { "email": "legal@acme.com", "name": "A. Counsel",
        "role": "signer", "routingOrder": 0 },
      { "email": "ops@northwind.co", "name": "N. Ops",
        "role": "signer", "routingOrder": 1 }
    ],
    "fields": [
      { "type": "signature", "page": 3, "x": 120, "y": 190,
        "width": 180, "height": 40, "recipientIndex": 0 },
      { "type": "date_signed", "page": 3, "x": 320, "y": 190,
        "width": 120, "height": 20, "recipientIndex": 0 }
    ]
  }'

Create and send accept an Idempotency-Key header so agent retries stay safe.

Agent MVP

What an agent needs to prepare, route, and close.

The API surface for agent-driven signing with a human checkpoint on every signature. Every capability runs through scoped credentials with the same audit rigor as dashboard actions.

Envelope lifecycle

Available

Create, send, void, and poll envelopes. Sequential and parallel routing with per-recipient routing order. Optional expiry.

Recipients and fields inline

Available

Define signers, CC viewers, routing order, optional access codes, and coordinate-placed fields in the same create call.

Scoped machine credentials

Available

ss_live_ keys with granular scopes, hashed at rest, revocable instantly, with last-used metadata. A key can never complete a signature.

Human signing checkpoint

Available

Every signature is made by a human through a one-time signing token — with consent capture, IP, and user agent recorded. UETA/ESIGN-clean by construction.

Status polling

Available

Poll envelope and per-recipient status at any time: draft, sent, viewed, partially_signed, completed, voided, expired.

Evidence retrieval

Available

Fetch the append-only audit trail, the flattened signed PDF, and the Certificate of Completion the moment an envelope completes.

Template instantiation

Available

Reusable templates with text-anchor field placement, instantiated in a single call. Managed entirely through the API.

Webhooks

Available

HMAC-signed lifecycle events with retry and backoff. Subscribe once; deliveries retry until acknowledged.

Idempotency keys

Available

Send Idempotency-Key on create and send so agent retries never duplicate envelopes or dispatch jobs.

Enterprise

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

Planned

Host signing pages on sign.yourcompany.com. TLS, DNS, and security policy under your control.

Organization-scoped resources

Available

Multi-tenant resource isolation. Every read and write is automatically scoped to the authenticated organization.

Role-based access control

In development

Least-privilege roles: Owner, Admin, Operator, Viewer. Scoped API keys inherit the creator's role boundaries.

Data residency

Planned

Choose the region where envelope data, documents, and audit trails are stored and processed.

SSO / SAML

Planned

Authenticate dashboard users through your identity provider. JIT provisioning and session enforcement.

Compliance exports

Planned

Bulk export audit trails, certificates, and evidence bundles in formats suited for SOC 2, legal discovery, and regulatory review.

Bulk operations

Planned

Send, void, or archive envelopes in batches. Asynchronous job status with progress polling.

Advanced branding

Planned

Full white-label control over signing pages, email templates, and certificate styling.

Response

Predictable JSON. Full state visibility.

Resources are UUID-identified and include status, UTC timestamps for every transition, and embedded recipients and fields so agents see the whole envelope in one call. Validation errors return structured issue lists with field paths.

200 OKSuccess
201 CreatedResource created
400 Bad RequestValidation failed (issue list)
403 ForbiddenAPI key missing scope
JSON
{
  "id": "3fe4ec85-219e-4871-ab5c-447b9006b58d",
  "status": "partially_signed",
  "name": "MSA — Acme & Northwind",
  "routingMode": "sequential",
  "documentId": "2a3fd57b-764a-40d9-b9e9-015b8811da26",
  "createdAt": "2026-07-02T09:23:17Z",
  "sentAt": "2026-07-02T09:23:18Z",
  "completedAt": null,
  "expiresAt": "2026-08-01T09:23:17Z",
  "completedPdfObjectKey": null,
  "certificateObjectKey": null,
  "recipients": [
    { "id": "d41c…", "email": "legal@acme.com",
      "role": "signer", "routingOrder": 0,
      "status": "signed", "signedAt": "2026-07-02T11:02:44Z" },
    { "id": "9b7f…", "email": "ops@northwind.co",
      "role": "signer", "routingOrder": 1,
      "status": "sent", "signedAt": null }
  ],
  "fields": [ /* type, page, x, y, width, height, value */ ]
}
Reference

Endpoints

All paths are prefixed with https://api.sumosign.app. Agent endpoints authenticate with an API key; recipient signing endpoints authenticate with the one-time token in the emailed link.

Documents

Upload source PDFs. Hashed with SHA-256 at upload for tamper evidence.

POST/v1/documents
Upload a PDF (multipart).
GET/v1/documents/{id}
Metadata: page count, size, content hash.

Envelopes

Create, send, and manage signing packets. Recipients and fields are defined inline at creation.

POST/v1/envelopes
Create with recipients, routing, and field placements.
GET/v1/envelopes
List envelopes for your organization.
GET/v1/envelopes/{id}
Envelope, recipient, and field status.
POST/v1/envelopes/{id}/send
Dispatch signing emails to the current routing group.
POST/v1/envelopes/{id}/void
Void before completion. Reason required and audit-logged.
GET/v1/envelopes/{id}/audit
Append-only audit trail with actor attribution.
GET/v1/envelopes/{id}/download
Flattened, signed PDF once completed.
GET/v1/envelopes/{id}/certificate
Certificate of Completion PDF.

Recipient signing (public)

The human checkpoint. No account, no API key — a one-time signing token in the emailed link is the only authority.

GET/v1/sign/{token}
Signing session: envelope, recipient, fields. Records first view.
GET/v1/sign/{token}/document
The PDF for review before signing.
POST/v1/sign/{token}/consent
Record electronic-business consent (UETA/ESIGN).
POST/v1/sign/{token}/complete
Submit field values and sign. Consent required.
POST/v1/sign/{token}/decline
Decline with a reason. Token is revoked.

Templates

Reusable configurations with text-anchor field placement.

POST/v1/templates
Create a template.
POST/v1/templates/{id}/instantiate
Create an envelope from a template.

Webhooks

HMAC-signed lifecycle events with retry and backoff.

POST/v1/webhooks
Create a subscription.
GET/v1/webhooks
List active subscriptions.
Webhooks

HMAC-signed event deliveries.

Subscribe to envelope events and receive structured payloads at your URL. Failed deliveries retry with exponential backoff and every attempt is logged. The event vocabulary below matches the audit log, so polling and webhooks always agree.

Signed payloads
Verify the X-SumoSign-Signature header.
Retry with backoff
Up to 15 attempts over 3 days. View delivery logs in the dashboard.
Idempotent
Each event includes a unique event_id for deduplication.
JSON
{
  "event_id": "evt_8k2m9p...",
  "type": "envelope.completed",
  "created_at": "2026-07-02T14:33:02Z",
  "data": {
    "envelope_id": "env_9f3k2m...",
    "status": "completed",
    "completed_at": "2026-07-02T14:33:01Z",
    "certificate_url": "/v1/envelopes/env_9f3k2m.../certificate"
  }
}
envelope.createdenvelope.sentenvelope.viewedenvelope.completedenvelope.voidedenvelope.expiredrecipient.email_deliveredrecipient.viewedrecipient.consentedrecipient.signedrecipient.declinedsigner.replacedreminder.sentwebhook.deliveredwebhook.failedapikey.used
SDKs

Use the REST API today.

Call the API from any HTTP client. Typed SDKs for Node.js and Python are in active development — until they ship, start from the OpenAPI spec or the agent guide at llms.txt.

Get started

Build signing into your product.

Create a scoped API key in the portal and paste the agent block above into Claude, Cursor, or your own orchestrator.

Get an API keyapi@sumosign.app