Lexical

This page defines the main concepts you’ll see across the API and documentation. Each term links to the relevant docs for details.

For deeper dives, see:

Envelope lifecycle

Envelope structure

API security

Envelope

An envelope is a single signing request: one or more documents, a set of recipients, and blocks (signature fields, text, images) placed on the documents. You create it in draft status, add recipients and blocks, then send it. After sending, recipients can open and sign. When all required signatures are collected, the envelope is completed and you can download the signed document and audit proof. See Envelope lifecycle and Envelope structure for details, and Create and send your first envelope and Working with the API.

Workspace

A workspace is the container for envelopes, templates, contacts, and team members in your Subnoto account. API calls can be scoped by workspaceUuid; in most endpoints it is optional and the team’s default workspace is used when omitted. You create API keys per team; those keys can access workspaces the team owns. See API keys, Pagination for list endpoints, and How to isolate documents with workspaces.

Recipient

A recipient is a person who must open, and optionally sign, an envelope. You add recipients to an envelope (by email/name, or by linking a contact or workspace member). Signature blocks are assigned to a recipient by recipientEmail. Recipients receive a link to open the envelope (or you embed the signing UI and pass an iframe token). See Create and send your first envelope and Envelope structure.

Block

A block is a placed element on a document page: a signature field, a text field, or an image. You define blocks with position (page, x, y) and, for signatures, the recipient who must sign. Block types include signature (signer signs here), text (fixed or templated text such as email/fullname), and image. You can place blocks manually via the API or use Smart Anchors to have Subnoto detect placeholders in the PDF. See Create and send your first envelope and Envelope structure.

Iframe token

An iframe token is a short-lived, one-time credential that authorizes loading the Subnoto signing UI for a specific envelope and signer. You create it on your backend with POST /public/authentication/create-iframe-token (workspace, envelope, signer email); it is only available when the recipient has verification type (email or SMS) enabled. You never send API keys to the frontend; instead you pass the token to your app so it can build the embed URL and show the signing iframe. See Iframe token and Embedded signing.

Webhooks and events

Webhooks are HTTP POST requests sent by Subnoto to a URL you configure when envelope-related events occur. You use them to know when an envelope is sent, opened, signed, or completed. Important events:

• ENVELOPE_SIGNED - A recipient signed the document.
• ENVELOPE_COMPLETED - All required signatures are collected; use this to download the signed document and proof.

Other events include ENVELOPE_CREATED, ENVELOPE_SENT, ENVELOPE_OPENED, ENVELOPE_DECLINED, and ENVELOPE_CANCELED. See Setting up webhooks and Payload reference.