One Call Sends an Agreement. A Signed Event Says When It Is Done.
A REST API with scoped keys, a test mode that contacts nobody, signed webhooks and SDKs generated from the same OpenAPI spec. Signing itself always stays with the signer.
- Test keys never email, message or charge
- An idempotency key on every create and send
- OpenAPI 3.1 spec, public to read
curl -X POST \ https://api.flowverify.co/v1/templates/{template_id}/envelopes \ -H "Authorization: Bearer fv_test_xxxxxxxx" \ -H "Idempotency-Key: po-2611-102" \ -H "Content-Type: application/json" \ -d '{ "reference": "po-2611-102", "recipients": [{ "role": "signer_1", "name": "Farah Qureshi", "email": "[email protected]" }], "variables": { "vendor_name": "Nandi Freight" }, "subject": "Vendor agreement for signature" }'status: "sent". Repeat the call with the same Idempotency-Key and you get the same envelope, not a second send.import { FlowVerify, idempotencyKey } from '@flowverify/sdk'; const fv = new FlowVerify({ apiKey: process.env.FV_API_KEY! }); const envelope = await fv.templates.createEnvelope( templateId, { reference: 'po-2611-102', recipients: [{ role: 'signer_1', name: 'Farah Qureshi', email: '[email protected]', }], variables: { vendor_name: 'Nandi Freight' }, }, { idempotencyKey: idempotencyKey('po', '2611-102') },);npm install @flowverify/sdk For Node.js 18.17 or later, Bun and Deno. Every create and send carries an idempotency key, so a retry never runs a request twice.import osfrom flowverify import FlowVerify, idempotency_key with FlowVerify(api_key=os.environ["FV_API_KEY"]) as fv: envelope = fv.templates.create_envelope( template_id, reference="po-2611-102", recipients=[{ "role": "signer_1", "name": "Farah Qureshi", "email": "[email protected]", }], variables={"vendor_name": "Nandi Freight"}, idempotency_key=idempotency_key("po", "2611-102"), )pip install flowverify For Python 3.10 or later, built on httpx. Methods return typed models, and one error type carries the code and the request id.{ "mcpServers": { "flowverify": { "url": "https://mcp.flowverify.co/mcp", "headers": { "Authorization": "Bearer fv_test_xxxxxxxx", "X-Agent-Mandate": "<mandate id>" } } }}.cursor/mcp.json, then ask the agent to send the vendor agreement. It calls send_from_template, shows a preview and sends only with confirm: true.Quickstart
From a Test Key to a Signed PDF
Four steps, each with the request or the event you will see. Nothing here emails a real person or costs anything.
- 01
Create a Test Key
In the dashboard, open Developers, then API keys, and create a key in the Test environment. Give it the scopes this flow uses:
templates:read,envelopes:send,embedded:signandwebhooks:manage.The key is shown once.
GET /meworks with any valid key and tells you which workspace and scopes it carries.GET /me
200Request
curl https://api.flowverify.co/v1/me \ -H "Authorization: Bearer fv_test_xxxxxxxx"Response, trimmed
{ "success": true, "data": { "object": "account", "organization": { "name": "Kiran Exports Private Limited" }, "api_key": { "prefix": "fv_test_Q7mN", "environment": "test", "scopes": [ "templates:read", "envelopes:send", "embedded:sign", "webhooks:manage" ] } }, "request_id": "fa9ab28f-6eb0-4141-b526-7f3dc110d869"} - 02
Send From a Template
A template carries the document, the signing roles and the field positions, so sending is a single call. Assign a person to each role and fill fields by variable name.
The response is the envelope with
status: "sent". Because the key is a test key, nobody is emailed and nothing is charged.POST /templates/{id}/envelopes
201Request body
{ "reference": "po-2611-102", "recipients": [{ "role": "signer_1", "name": "Farah Qureshi", "email": "[email protected]" }], "variables": { "vendor_name": "Nandi Freight", "start_date": "1 December 2026" }}Response, trimmed
{ "success": true, "data": { "object": "envelope", "id": "3f6a2b1c-9d4e-4f70-8a21-5c7e9b0d1a42", "reference": "FV-2611-102", "external_reference": "po-2611-102", "status": "sent", "is_test": true, "sent": true }} - 03
Receive envelope.completed
No email goes out in test mode, so open the signing yourself: create a signing session for the recipient, open its URL and enter the test code
000000.When the last signer finishes, the event reaches your endpoint. It carries
livemode: falseand a signature you can check before you trust it.POST https://hooks.kiranexports.in/flowverify
signedHeaders
X-FV-Event-Type: envelope.completedX-FV-Attempt: 1X-FV-Signature: t=1794549269,v1=42f84ec8…a131ca75Body, trimmed
{ "id": "5d3c7a1e-0b6f-4c1d-9a52-7e3f8b2c4d10", "object": "event", "type": "envelope.completed", "api_version": "2026-09-28", "livemode": false, "occurred_at": "2026-11-13T05:54:29.000Z", "data": { "envelope": { "id": "3f6a2b1c-9d4e-4f70-8a21-5c7e9b0d1a42", "reference": "FV-2611-102", "external_reference": "po-2611-102", "status": "completed", "is_test": true } }, "delivery": { "id": "9a1f6c02-33d1-4be7-8f0a-2c1d5e6f7a81", "attempt": 1 }} - 04
Download the Signed PDF and the Evidence Pack
Once the status is
completed, the signed PDF, the Certificate of Completion and the evidence pack are ready. Downloads stream through the API after the ownership check. There are no long-lived public links.The evidence pack is one ZIP: the signed PDF, the certificate, the audit trail as JSON, a manifest with the SHA-256 of every entry, and a pre-filled certificate under section 63(4)(c) of the Bharatiya Sakshya Adhiniyam, 2023, for the person in charge of the system to complete in Part A and an expert in Part B.
Downloads
scope envelopes:readGET
/envelopes /{id} /files /{fileId} /download One signed PDF
GET
/envelopes /{id} /download ZIP of every file, with the certificate
GET
/envelopes /{id} /certificate The Certificate of Completion
GET
/envelopes /{id} /evidence-pack ZIP of the evidence pack
Inside the evidence pack
- signed.pdf
- certificate.pdf
- audit.json
- events.json
- recipients.json
- bsa-s63-certificate.pdf
- manifest.json
- README.txt
Webhooks
A Signed Event for Every Envelope Change
Subscribe an HTTPS endpoint to exact event types, to a wildcard such as envelope.*, or to everything. FlowVerify posts a small signed body, retries on failure and keeps every attempt in a log you can replay.
X-FV-Signatureis an HMAC-SHA256 of the timestamp and the raw body. Reject anything older than five minutes.- Delivery is at least once. Dedupe on the event id.
GET /webhooks/sample/{event}returns a sample body for any event type, before a real one happens.- Payloads are thin: ids and statuses, plus name, email and role on recipient events. Fetch the rest through the API.
Retry schedule after a failed delivery
- 1 min
- 5 min
- 30 min
- 2 h
- 8 h
- 24 h
- envelope.sent
- envelope.viewed
- envelope.completed
- envelope.declined
- envelope.expired
- envelope.voided
- recipient.signed
- recipient.declined
- approval.approved
- reminder.sent
- bulk_send.completed
- sign_form.submitted
POST /flowverify HTTP/1.1X-FV-Event-Type: envelope.completedX-FV-Delivery-Id: 9a1f6c02-33d1-4be7-8f0a-2c1d5e6f7a81X-FV-Attempt: 1X-FV-Signature: t=1794549269,v1=42f84ec8…a131ca75{ "id": "5d3c7a1e-0b6f-4c1d-9a52-7e3f8b2c4d10", "type": "envelope.completed", "livemode": false, "data": { "envelope": { "status": "completed" } }}The timestamp is inside five minutes
t is 1 second old
HMAC-SHA256 of t, a dot and the raw body equals v1
compared in constant time
This event id has not been handled before
delivery is at least once
200Answered at once. The real work runs after the response.
Delivery log · 30 days
envelope.completedDelivered200Attempt 1Replayrecipient.signedDelivered200Attempt 1Replayenvelope.sentDelivered200Attempt 2ReplayFirst attempt answered 503. Retried after 1 minute.
Test mode
The Same API, With Nobody on the Other End
A test key runs the full lifecycle for local development, CI and demos. The difference from a live key is small enough to fit in one table.
Live key
fv_live_xxxxxxxx
Test key
fv_test_xxxxxxxx
is_test: falseis_test: true000000, never delivered409. Use the standard method.livemode: truelivemode: falseEverything else is real. Documents are certified, statuses move as they would live, the audit trail and the Certificate of Completion are produced, and webhooks reach your endpoints. Moving to live is a key swap.
Embedded signing
Embedded signing
Open the Signing Inside Your Own App
Your server asks for a signing session for one recipient and opens its URL, as a redirect or in a frame. The signer still passes every check the sender set: the one-time code, consent, and Aadhaar eSign in a full window.
- The session URL works once and for 15 minutes. Create it when the person clicks Sign.
- It frames only on origins you allow-list under Developers, Embed origins.
- The frame posts
ready,signed,declinedorerrorto your page. A redirect comes back with?status=and nothing else. - It needs the
embedded:signscope, whichenvelopes:senddoes not imply.
POST /envelopes/{id}/recipients/{recipientId}/signing-session{ "embed_origin": "https://portal.kiranexports.in", "return_url": "https://portal.kiranexports.in/agreements/done"}Kiran Exports · Partner portal
Your application
Agreement
Lease Deed — Indiranagar (2027 renewal)
FV-2611-130 · sent by Shalini Bose
Signing session
- Single use, expires in 15 minutes
embed_originis on the allowlist
Messages from the frame
readyDocument is opensignedSigned or approveddeclinedDeclinederrorExpired or already used
iframe · FlowVerify signer

The rest of the contract
Fields, Variables, Bulk Jobs and Safe Retries
The smaller parts of the API, each shown with the request or the response you will actually see.
Place Fields by Quoting the Page
When you do not know the coordinates, quote text that is printed on the page and the field lands next to it. If the text appears more than once, occurrence picks the match, and occurrence: "all" puts a field on every one.
Lease deed · page 6
Signature of Lessee
Date: ______________
PUT /envelopes/{id}/fields
{ "fields": [{ "file_id": "{fileId}", "recipient_id": "{recipientId}", "type": "signature", "anchor": { "text": "Signature of Lessee", "placement": "above" } }]}Fill a Template From Your Data
A template variable is a field’s data label. Placeholders in the document are detected, listed on the template and filled by name.
Dear {{ employee_name }},
Your start date is Start date: ____
Filled by name
Dear Rohan Iyer,
Your start date is 1 December 2026
"variables": { "employee_name": "Rohan Iyer", "start_date": "1 December 2026"}Bulk Send, One Envelope Each
One draft fans out to thousands of recipients in the background. Poll the job, or wait for bulk_send.completed.
bulk_send_jobrunningPolicy acknowledgement 2026
- total_
recipients - 240
- succeeded
- 149
- failed
- 0
- Rohan Iyer · own envelopesigned
- Farah Qureshi · own envelopeviewed
- 238 more, one envelope eachsent
A Retry Never Sends Twice
Send an Idempotency-Key on anything that creates or sends. The same key and body replay the first response for 24 hours.
Idempotency-Key: po-2611-102
- 201
First request
Envelope FV-2611-102 sent
- 409
Same key, while it still runs
idempotency_conflict
- 201
Same key, same body
Idempotent-Replayed: true
- 422
Same key, other body
idempotency_mismatch
One Error Shape, Stable Codes
Every error has the same body. code is safe to branch on, and request_id is what support will ask for.
HTTP 400X-Request-Id on every response
{ "success": false, "code": "validation_failed", "message": "The request is invalid.", "request_id": "fa9ab28f-6eb0-4141-…", "details": { "errors": [ { "param": "recipients[0].email" } ] }}The Same API, Handed to an Agent
The MCP server gives Claude, Cursor and other agents 23 tools over this API, with the same scopes. A mandate adds limits an admin sets, and a refusal names the limit that stopped it.
The 21st send of the day
POST /v1/templates/{id}/envelopesAuthorization: Bearer fv_live_xxxxxxxxX-Agent-Mandate: 2f1c3e5a-7b9d-4e2f-…{ "recipients": [{ "role": "signer_1", "name": "Farah Qureshi", "email": "[email protected]" }]}Refused, nothing sent403
{ "success": false, "code": "mandate_limit_exceeded", "details": { "limit": "max_sends_per_day", "max_sends_per_day": 20, "used_today": 20, "day": "2026-11-13" }}Zapier, Make and n8n
The Zapier app has three real-time triggers, two actions and a search. Make and n8n use the same webhooks, sample bodies and polling.
FlowVerify app for Zapier
- Triggers
- Envelope SentEnvelope CompletedEnvelope Declined
- Actions
- Send Envelope From TemplateCreate Draft Envelope
- Search
- Find Envelope
/v1
Versioned in the Path
Inside /v1 changes are additive only: new endpoints, new optional fields, new event types. Anything that renames or removes something ships as /v2, and retirements are announced with Deprecation and Sunset headers.
limit · offset · has_more
Lists You Can Page and Poll
Every list takes limit, up to 100, and offset, and says whether more remain. For polling, updated_since returns only the envelopes that changed at or after the instant you pass.
openapi.json
An OpenAPI 3.1 Contract
Every endpoint, schema and error code, public to download without a key. The reference, both SDKs and a Postman collection are generated from it.
Console and security
Keys, Deliveries and Usage Live in the Dashboard
There is no separate developer login. The people who administer your workspace administer its API access, under Developers: keys, webhooks, delivery logs, embed origins and usage.
ERP integrationLive
fv_live_EWSg…envelopes:send · templates:readActiveUsed 2 min agoProcurement agentLiveAgent key
fv_live_9KdR…envelopes:send · templates:readActiveUsed 11:24StagingTest
fv_test_Q7mN…envelopes:send · webhooks:manageActiveUsed YesterdayOld CRM syncLive
fv_live_2PxA…envelopes:readRevokedUsed 14 Oct
Copy this key now. It will not be shown again.
fv_test_••••••••••••••••••••••••
Copy- API keys
- Scopes, an expiry date, an IP allowlist and rotation for each key.
- Webhooks
- Subscriptions, a test delivery and secret rotation.
- Delivery log
- Status, attempts and replay for every delivery, kept for 30 days.
- Embed origins
- The origins that may frame a signing session.
- Usage
- Requests, error rate, 429s and latency for each key, with a CSV export.
- Test documents
- Marked TEST in the Documents list, with a filter to hide them.
What Holds for Every Request
- Keys are shown once. Rotation keeps the old key valid for 24 hours, and a revoked key stops working everywhere within a minute.
- Each key carries its own scopes, and can be limited to your own IP addresses.
- The workspace comes from the key, never from the request. An id from another workspace gets the same 404 as one that does not exist.
- Every response is an explicit, allow-listed shape. No storage paths, no internal metadata.
- URLs you supply are checked: HTTPS only, with private networks and cloud-metadata addresses refused.
- Keys travel in the Authorization header and nowhere else, over HTTPS only.
What a Key Can Never Do
- Sign, initial or approve for a recipient
- Read or change billing, members, roles or security settings
- Sign in to the dashboard
Documentation
Go Deeper in the Docs
Each link opens developers.flowverify.co in a new tab.
- Quickstart (opens the developer docs in a new tab)Create a key, check the connection and send from a template.
- API reference (opens the developer docs in a new tab)Every endpoint, parameter and schema, rendered from the OpenAPI spec.
- SDKs (opens the developer docs in a new tab)TypeScript and Python, with idempotency, pagination and retries built in.
- Webhooks (opens the developer docs in a new tab)Subscriptions, signatures, retries, the delivery log and replay.
- Embedded signing (opens the developer docs in a new tab)Sessions, allow-listed origins, redirect mode and frame mode.
- Test mode (opens the developer docs in a new tab)What a test key does differently, and how to sign a test document.
- MCP server (opens the developer docs in a new tab)Connect Claude Code, Cursor or VS Code, and the 23 tools they get.
- Changelog (opens the developer docs in a new tab)Every customer-visible change to the API, newest first.
Limits are per API key and per minute, never per IP address, so several of your servers behind one address do not compete. The default is 120 requests a minute. Send, remind, bulk send, send from a template, file uploads and the webhook test, secret rotation and replay calls share a tighter 30 a minute. Every response carries RateLimit headers, and a 429 carries Retry-After. The Usage tab under Developers shows requests, error rate, 429s and latency for each key.
Yes, test mode. A key that starts with fv_test_ runs the whole lifecycle, including certification, the audit trail, the certificate and webhooks, while nobody is emailed, texted or messaged on WhatsApp and nothing is charged. Recipients verify with the fixed code 000000. Moving to live is a key swap: the endpoints, payloads and error codes are identical.
The delivery is retried with a growing delay: 1 minute, 5 minutes, 30 minutes, 2 hours, 8 hours, then 24 hours. After that it is marked dead and stays in the 30-day delivery log, where you can replay it. An endpoint that fails 25 times in a row is paused and the workspace admins are told.
TypeScript (@flowverify/sdk, for Node.js 18.17 or later, Bun and Deno) and Python (flowverify, for Python 3.10 or later). Both are generated from the same OpenAPI 3.1 document as the API reference, and add idempotency keys, pagination helpers, safe retries and webhook verification. For any other language, generate a client from the spec or import the Postman collection.
No. Recipients always sign in the FlowVerify signer app, with their own verification and consent. The API can open that same flow inside your app with an embedded signing session, and it can sign with your own organisation’s certificate. It cannot sign, initial or approve on behalf of a recipient.
The version is in the path. Inside /v1 changes are additive only: new endpoints, new optional fields and new event types. Anything that renames or removes something ships as /v2 alongside /v1. Every customer-visible change is listed in the changelog, and a retirement is announced there and with Deprecation and Sunset headers.
Book a demo
See It on Your
Own Agreements
Bring one agreement you send often. We run it through FlowVerify with you, live, from first draft to signed record.
What you get
- A live walkthrough on one of your own agreements
- A workspace set up for your team
- Answers from the people who build it