API Reference

Retrieve documents with optional filtering.

curl -X GET "https://zsign.io/api/documents?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "items": [
    {
      "document_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Contract.pdf",
      "status": "pending",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 1,
  "offset": 0,
  "limit": 20
}

List envelopes in the caller's organization. Same filter semantics as the dashboard JWT list. Includes unsent drafts (status draft or ready_to_send, session_id null) in the default All mix. limit max 50. Each item includes thin recipients[] (recipient_id, email, name, status, can_remind) for Remind. Sender email and the rich session payload stay on GET /api/v1/documents/{document_id}.

curl -X GET "https://zsign.io/api/v1/documents?q=Contract&limit=20" \
  -H "Authorization: Bearer zs_live_xxxxxxxxxxxxxxxxxxxxxxxx"

{
  "items": [
    {
      "document_id": "550e8400-e29b-41d4-a716-446655440000",
      "session_id": "660e8400-e29b-41d4-a716-446655440000",
      "name": "Contract.pdf",
      "status": "pending",
      "created_at": "2024-01-15T10:30:00Z",
      "recipient_count": 1,
      "completed_recipient_count": 0,
      "recipients": [
        {
          "recipient_id": "770e8400-e29b-41d4-a716-446655440000",
          "email": "signer@example.com",
          "name": "Alex Signer",
          "status": "pending",
          "can_remind": true
        }
      ]
    }
  ],
  "total": 1,
  "offset": 0,
  "limit": 20
}

Upload a PDF and send it for signing in one request. PDFs must include field annotations using {type:party:name} syntax (e.g., {signature:signer}, {text:signer:name}). The party must exactly match a recipient's "role" — matching is case-sensitive, so {signature:signer} pairs with "role": "signer", not "Signer". Add * after type for required fields: {type*:party:name}. The sender's account default also applies: "Require new fields by default" (Settings → Sending) is on by default and makes every unstarred tag a required field; senders who turn it off get optional fields unless they star them. * marks required either way. Supported types: signature, text, date, initials, radio (radio is four parts and visible-text only — see notes below).

[
  {
    "email": "john@example.com",
    "name": "John Doe",
    "role": "signer"
  }
]

curl -X POST https://zsign.io/api/v1/documents/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@contract.pdf" \
  -F 'recipients=[{"email":"john@example.com","name":"John Doe","role":"signer"}]'

{
  "document_id": "550e8400-e29b-41d4-a716-446655440000",
  "session_id": "660e8400-e29b-41d4-a716-446655440000",
  "signing_urls": [
    {
      "recipient_email": "john@example.com",
      "signing_url": "https://zsign.io/sign/eyJ..."
    }
  ]
}

Every field on a document, with its submitted value once the signer has answered it — the way to read back which radio option a signer chose, or what they typed into a text field. Accepts either the original document id or the completed document id (the one the document.completed webhook carries). Unanswered optional fields report "value": null, not an omitted key. Field values can carry personal data, so this route is API-key/owner scoped only.

curl -X GET "https://zsign.io/api/v1/documents/{document_id}/fields" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "document_id": "550e8400-e29b-41d4-a716-446655440000",
  "session_id": "660e8400-e29b-41d4-a716-446655440000",
  "fields": [
    {
      "id": "client:term_sheet_option",
      "type": "radio",
      "party": "client",
      "name": "term_sheet_option",
      "group": "term_sheet_option",
      "required": true,
      "page": 3,
      "value": "Option 2",
      "submitted_at": "2026-08-19T14:32:00+00:00"
    },
    {
      "id": "client:full_name",
      "type": "text",
      "party": "client",
      "name": "full_name",
      "required": true,
      "page": 1,
      "value": null,
      "submitted_at": null
    },
    {
      "id": "client:signature",
      "type": "signature",
      "party": "client",
      "name": "signature",
      "required": true,
      "page": 1,
      "status": "pending",
      "signed_at": null
    }
  ]
}

Upload one or more PDFs as an unsent Draft (no credit debit, no invites), or stamp a saved template. Provide exactly one of `file`/`files` or `template_id`. `file` is the single-document form; `files` is repeatable. When both are sent the order is `file` first, then `files`. `document_names` is an optional JSON array of display names aligned to that order. `role_mapping` (template only) is a JSON object `{source_role: destination_role}`; unmapped roles stay literal. `fields` cannot be combined with `template_id`. The same `file` + `files` + `document_names` shape is accepted on POST /api/v1/documents/send. Response `documents[]` is `{id, name, filename, page_start, page_count, position}` plus `revision`.

{
  "document_names": [
    "NDA",
    "MSA"
  ]
}

curl -X POST "https://zsign.io/api/v1/documents/drafts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "files=@nda.pdf" \
  -F "files=@msa.pdf" \
  -F 'document_names=["NDA","MSA"]'

{
  "document_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "draft",
  "revision": 1,
  "documents": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440000",
      "name": "NDA",
      "filename": "nda.pdf",
      "page_start": 1,
      "page_count": 1,
      "position": 0
    },
    {
      "id": "770e8400-e29b-41d4-a716-446655440000",
      "name": "MSA",
      "filename": "msa.pdf",
      "page_start": 2,
      "page_count": 3,
      "position": 1
    }
  ]
}

API-key twin of POST /api/documents/drafts/{id}/save-as-template. Copies the draft's current bytes and parsed_fields into a new reusable template. Free. The draft itself is unchanged. There is no blank-template flow.

{
  "name": "Std NDA"
}

curl -X POST "https://zsign.io/api/v1/documents/drafts/{document_id}/save-as-template" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Std NDA"}'

{
  "id": "22222222-2222-2222-2222-222222222222",
  "name": "Std NDA",
  "filename": "contract.pdf",
  "parties": [
    "signer"
  ],
  "field_count": 1,
  "document_count": 1
}

API-key twin of GET /api/documents/templates. Every template the caller's org owns, with role names (`parties`), updated_at, and public-link status. Same rows as the dashboard list — not a second template model.

curl -X GET "https://zsign.io/api/v1/documents/templates" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "templates": [
    {
      "id": "22222222-2222-2222-2222-222222222222",
      "name": "Std NDA",
      "parties": [
        "signer"
      ],
      "field_count": 1,
      "document_count": 1
    }
  ],
  "total": 1
}

Append one uploaded PDF, or every document of a saved template, to a Draft envelope. Provide exactly one of `file` or `template_id`. Inserting a template adds all of its documents; each counts toward `MAX_ENVELOPE_DOCUMENTS` (default 10). `role_mapping` (template only) is a JSON object `{source_role: destination_role}`; unmapped roles stay literal.

{
  "template_id": "880e8400-e29b-41d4-a716-446655440000",
  "role_mapping": {
    "customer": "client"
  }
}

curl -X POST "https://zsign.io/api/v1/documents/drafts/{document_id}/documents" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@msa.pdf" \
  -F "name=MSA"

{
  "document_id": "550e8400-e29b-41d4-a716-446655440000",
  "revision": 2,
  "documents": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440000",
      "name": "a",
      "filename": "a.pdf",
      "page_start": 1,
      "page_count": 1,
      "position": 0
    },
    {
      "id": "770e8400-e29b-41d4-a716-446655440000",
      "name": "T",
      "filename": "t.pdf",
      "page_start": 2,
      "page_count": 1,
      "position": 1
    }
  ]
}

Set the order of documents in a Draft. `order` must list every `documents[].id` exactly once. Field pages are remapped to the new ranges. `revision` is the optimistic concurrency token.

{
  "order": [
    "770e8400-e29b-41d4-a716-446655440000",
    "660e8400-e29b-41d4-a716-446655440000"
  ],
  "revision": 2
}

curl -X PUT "https://zsign.io/api/v1/documents/drafts/{document_id}/documents/order" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"order":["770e8400-e29b-41d4-a716-446655440000"],"revision":2}'

{
  "document_id": "550e8400-e29b-41d4-a716-446655440000",
  "revision": 3
}

Change the display name of one document inside a Draft. Path `{part_id}` is `documents[].id`. Display metadata only — no bytes rebuilt, no field moved. `revision` is the optimistic concurrency token.

{
  "name": "Second",
  "revision": 2
}

curl -X PATCH "https://zsign.io/api/v1/documents/drafts/{document_id}/documents/{part_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Second"}'

{
  "document_id": "550e8400-e29b-41d4-a716-446655440000",
  "revision": 3
}

Remove one document from a Draft. Path `{part_id}` is `documents[].id`. An envelope must keep at least one document (`last_document`). `?revision=` is the optimistic concurrency token.

curl -X DELETE "https://zsign.io/api/v1/documents/drafts/{document_id}/documents/{part_id}?revision=2" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "document_id": "550e8400-e29b-41d4-a716-446655440000",
  "revision": 3
}

Download the sealed, signed PDF. `{completed_document_id}` is the id from get-envelope-status / document.completed; the original document id from send / list also works and resolves to that document's most recent completed session (a session id does not). `?document=` is one `documents[].id` to download just that document (its pages plus the certificate pages — an extract; the certificate hash identifies the full envelope). `?format=zip` returns every document as its own PDF in one archive. Do not combine `document` and `format`.

curl -X GET "https://zsign.io/api/v1/documents/{completed_document_id}/download?document={part_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o signed.pdf

(binary)

Recipient signing URLs for an already-sent envelope. Same `{recipient_email, recipient_name, signing_url, token}` objects POST /api/v1/documents/send returns as `signing_urls`. These are the ordinary agent-link values — valid iframe `signingUrl`s for `@zsign/embed`. Optional `recipient_email` keeps one recipient. Drafts and documents with no session 404.

curl -X GET "https://zsign.io/api/v1/documents/{document_id}/signing-urls" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "document_id": "550e8400-e29b-41d4-a716-446655440000",
  "session_id": "660e8400-e29b-41d4-a716-446655440000",
  "signing_urls": [
    {
      "recipient_email": "alice@example.com",
      "recipient_name": "Alice",
      "signing_url": "https://app.example/sign/TOKEN",
      "token": "TOKEN"
    }
  ]
}

Send one signing reminder to a still-unsigned recipient. Same policy as the dashboard Remind button and the cron sweep: cap, spacing, sequential can_sign_now. REMINDERS_ENABLED does not apply. Envelopes sent with send_invite=false are refused unless override_send_invite is true. MCP remind_envelope is a thin wrapper over this route (envelopes:send).

{
  "override_send_invite": false
}

curl -X POST "https://zsign.io/api/v1/documents/{document_id}/recipients/{recipient_id}/remind" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "session_id": "660e8400-e29b-41d4-a716-446655440000",
  "recipient_id": "770e8400-e29b-41d4-a716-446655440000",
  "email": "john@example.com",
  "reminder_count": 1,
  "reminder_last_at": "2026-09-06T12:00:00Z",
  "sent": true
}

Terminate a live envelope. Signing links stop working immediately and pending recipients are emailed. The send credit is refunded only if no recipient has viewed, signed, or declined the envelope (declining does not require a prior view, so it can block the refund on its own) and no access has otherwise been recorded against it. Idempotent: voiding an already-voided envelope returns 200, not an error. The API-key equivalent is POST /api/v1/documents/{document_id}/void, which voids the newest session for a document.

{
  "reason": "Contract terms changed"
}

curl -X POST "https://zsign.io/api/sessions/{session_id}/void" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Contract terms changed"}'

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "document_id": "660e8400-e29b-41d4-a716-446655440000",
  "status": "voided",
  "voided_at": "2024-01-15T10:30:00Z",
  "reason": "Contract terms changed",
  "recipients_to_notify": 1,
  "credit_refunded": true,
  "credit_refund_skipped": null
}

Read the org's current singleton HTTP webhook configuration. Empty is 200 with a null body, not 404. Settings and API-key callers share this route.

curl https://zsign.io/api/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "url": "https://example.com/webhook",
  "events": [
    "document.signed",
    "document.completed"
  ],
  "enabled": true
}

Create or replace webhook configuration.

{
  "url": "https://example.com/webhook",
  "events": [
    "document.signed",
    "document.completed"
  ]
}

curl -X POST https://zsign.io/api/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhook",
    "events": ["document.signed", "document.completed"]
  }'

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "url": "https://example.com/webhook",
  "events": [
    "document.signed",
    "document.completed"
  ],
  "enabled": true,
  "secret": "whsec_..."
}

Retrieve the current account's branding configuration.

curl -H "Authorization: Bearer YOUR_API_KEY" https://zsign.io/api/branding

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "660e8400-e29b-41d4-a716-446655440000",
  "company_name": "Acme Corp",
  "logo_url": "https://storage.googleapis.com/zsign-public/branding/.../logo.png",
  "primary_color": "#2563eb",
  "custom_domain": null,
  "custom_domain_verified": false,
  "custom_domain_verified_at": null,
  "custom_domain_target": "zsign-frontend.onrender.com",
  "custom_domain_a_record": "216.24.57.1",
  "badge_removed": false,
  "embed_origins": [
    "https://app.acme.com"
  ],
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z"
}

Update company name, logo URL, and accent color shown on signing pages, emails, and the Certificate of Completion.

{
  "company_name": "Acme Corp",
  "primary_color": "#ff6600"
}

curl -X PUT https://zsign.io/api/branding \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"company_name": "Acme Corp", "primary_color": "#ff6600"}'

{
  "company_name": "Acme Corp",
  "primary_color": "#ff6600"
}

Upload a PNG, JPEG, or WebP logo (max 1MB, magic-byte validated -- no SVG). Stores it in public GCS and saves the URL onto the account's branding.

// multipart/form-data with a "file" field

curl -X POST https://zsign.io/api/branding/logo \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@logo.png"

{
  "logo_url": "https://storage.googleapis.com/zsign-public/branding/.../logo.png"
}

Start a $49/month White-label subscription via Stripe Checkout (100 envelopes included each month). Returns 409 if the account already has an active subscription.

curl -X POST https://zsign.io/api/branding/white-label/checkout \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_test_..."
}

Open the Stripe Billing Portal to manage or cancel the White-label subscription. Returns 400 if no subscription is on file.

curl -X POST https://zsign.io/api/branding/white-label/portal \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "portal_url": "https://billing.stripe.com/p/session/..."
}

Register a custom domain for outbound invite and completion emails via Resend. Requires an active White-label subscription (403 if not subscribed). Returns 409 if the domain is already claimed by another account.

{
  "domain": "mail.yourcompany.com"
}

curl -X PUT https://zsign.io/api/branding/sender-domain \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "mail.yourcompany.com"}'

{
  "sender_domain": "mail.yourcompany.com",
  "sender_domain_verified": false,
  "records": [
    {
      "record": "TXT",
      "name": "mail.yourcompany.com",
      "value": "resend-verify=..."
    }
  ]
}

Ask Resend to re-check DNS for the account's configured sender domain and report status. Not gated by subscription status, so an account whose subscription has lapsed can still confirm its DNS records.

curl -X POST https://zsign.io/api/branding/sender-domain/verify \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "sender_domain": "mail.yourcompany.com",
  "sender_domain_verified": true,
  "records": [
    {
      "record": "TXT",
      "name": "mail.yourcompany.com",
      "value": "resend-verify=...",
      "status": "verified"
    }
  ]
}

Remove the configured sender domain and deregister it from Resend. Not gated by subscription status, so an account whose subscription has lapsed can still clean up its DNS.

curl -X DELETE https://zsign.io/api/branding/sender-domain \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true
}

Configure the exact origins allowed to embed this account's signing pages in an iframe (default deny -- an empty list blocks all framing). Exact match only, https required except http://localhost[:port], no paths or wildcards, max 10. Parent SDKs: npm install @zsign/embed (createSigningEmbed) or @zsign/react (ZSignEmbed).

{
  "origins": [
    "https://app.yourcompany.com"
  ]
}

curl -X PUT https://zsign.io/api/branding/embed-origins \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"origins": ["https://app.yourcompany.com"]}'

{
  "embed_origins": [
    "https://app.yourcompany.com"
  ]
}