Working with the API

This page gives an overview of how to work with the Subnoto API: your backend creates envelopes and iframe tokens, your frontend embeds the signing UI (or you send links by email), webhooks notify your backend when the envelope is complete, and your backend downloads the signed document and proof.

What you can do

• Backend: Create envelopes (upload document, add recipients and blocks, send), create iframe tokens for embedded signing, and download the signed PDF and proof when the envelope is complete.
• Frontend: Request an iframe token from your backend and display the signing UI in an iframe (e.g. with SignEmbed); or redirect the signer to a Subnoto-hosted link.
• Webhooks: Your backend receives ENVELOPE_SIGNED and ENVELOPE_COMPLETED (and other events) at a URL you configure.

You need API keys on the backend only; never expose them in the frontend. Use the Encryption Proxy for curl and plain HTTP, or the TypeScript or Python SDK for direct, encrypted access.

Full flow (backend, frontend, webhooks)

The diagram below separates your backend (API client, webhook endpoint) from your frontend (e.g. the page that embeds the signing iframe). For a step-by-step implementation, see the Subnoto SDK demo (e.g. the Devis example: build a quote PDF, create an envelope with Smart Anchors, open signing in an iframe).

1. Your backend creates the envelope (upload document, add recipients and signature blocks, then send). For PDFs with Smart Anchors, you can use create-from-file with detectSmartAnchors: true and skip explicit add-recipients/add-blocks.
2. Your frontend asks your backend for an iframe token (envelope + signer). Your backend calls POST /public/authentication/create-iframe-token and returns the token so the frontend can build the embed URL and show the signing UI in an iframe. The recipient must have verification type (email or SMS) enabled; see Iframe token for details.
3. The signer completes the flow in the iframe (or via a link). Subnoto sends ENVELOPE_SIGNED and ENVELOPE_COMPLETED to your webhook endpoint (backend).
4. Your backend handles ENVELOPE_COMPLETED, then calls the API to download the signed document and the proof PDF.

Next steps

Create API keys

Pagination

Errors

Create and send your first envelope

Setting up webhooks

Download signed document and proof

SDKs

Embedded signing

Subnoto SDK demo (GitHub)