Skip to content
BTS 2026Met us at the summit?Claim your summit offer
api.flowverify.co/v1

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"  }'
201The envelope comes back with 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>"      }    }  }}
Put this in .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.

  1. 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:sign and webhooks:manage.

    The key is shown once. GET /me works with any valid key and tells you which workspace and scopes it carries.

    GET /me

    200

    Request

    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"}
  2. 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

    201

    Request 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  }}
  3. 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: false and a signature you can check before you trust it.

    POST https://hooks.kiranexports.in/flowverify

    signed

    Headers

    X-FV-Event-Type: envelope.completedX-FV-Attempt: 1X-FV-Signature: t=1794549269,v1=42f84ec8…a131ca75

    Body, 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 }}
  4. 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:read
    • GET/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-Signature is 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. 1 min
  2. 5 min
  3. 30 min
  4. 2 h
  5. 8 h
  6. 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
Your endpoint · hooks.kiranexports.in
Verified
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" } }}
  1. The timestamp is inside five minutes

    t is 1 second old

  2. HMAC-SHA256 of t, a dot and the raw body equals v1

    compared in constant time

  3. 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 1Replay
  • recipient.signedDelivered200Attempt 1Replay
  • envelope.sentDelivered200Attempt 2Replay

    First 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

Envelopes it creates
is_test: false
is_test: true
Invite, reminder and completion emails
Sent
Not sent
SMS and WhatsApp messages
Sent
Not sent
One-time codes for recipients
Random, delivered to the recipient
Always 000000, never delivered
Aadhaar eSign
Runs with the signer’s own Aadhaar OTP
Refused with 409. Use the standard method.
Charges
Counted as usual
Nothing is charged or counted
Envelopes the key can see
Live envelopes only
Test envelopes only
Webhook events
livemode: true
livemode: false
Signer app
As signers normally see it
A TEST banner on every screen

Everything 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, declined or error to your page. A redirect comes back with ?status= and nothing else.
  • It needs the embedded:sign scope, which envelopes:send does 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

Agreement

Lease Deed — Indiranagar (2027 renewal)

FV-2611-130 · sent by Shalini Bose

Waiting for your signature

Signing session

  • Single use, expires in 15 minutes
  • embed_origin is on the allowlist

Messages from the frame

  • readyDocument is open
  • signedSigned or approved
  • declinedDeclined
  • errorExpired or already used

iframe · FlowVerify signer

The FlowVerify signer screen inside the frame. It shows a lease deed sent by Kiran Exports and the steps the signer must complete: a one-time code by email, the e-signature consent, one signature and one detail.

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 field

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_jobrunning

Policy 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

  • First request

    Envelope FV-2611-102 sent

    201
  • Same key, while it still runs

    idempotency_conflict

    409
  • Same key, same body

    Idempotent-Replayed: true

    201
  • Same key, other body

    idempotency_mismatch

    422

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 400

{  "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 ZapierMaken8n

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.

OverviewAPI keysWebhooksEmbed originsUsage
  • ERP integrationLive

    fv_live_EWSg…envelopes:send · templates:read

    ActiveUsed 2 min ago
  • Procurement agentLiveAgent key

    fv_live_9KdR…envelopes:send · templates:read

    ActiveUsed 11:24
  • StagingTest

    fv_test_Q7mN…envelopes:send · webhooks:manage

    ActiveUsed Yesterday
  • Old CRM syncLive

    fv_live_2PxA…envelopes:read

    RevokedUsed 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

FAQ

Questions Developers Ask First

Something else on your mind? Book a demo and ask us.

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