Skip to content
BTS 2026Met us at the summit?Claim your summit offer
For developers & AI teams

Build Signing Into Your Product. Or Give an Agent a Mandate.

Scoped API keys, an idempotency key on every send, a test mode that never emails or charges anyone, and webhooks you can verify. When an agent takes over, it uses the same API through the MCP server, inside a mandate an admin sets.

  • TypeScript and Python SDKs
  • Signed webhooks
  • Agent actions named on the certificate

Test modenobody is emailed

Request→ api.flowverify.co

pending
POST /v1/templates/{id}/envelopesAuthorization: Bearer fv_test_••••••••Idempotency-Key: order-1042{ "reference": "order-1042",  "recipients": [{ "role": "signer_1",    "name": "Farah Qureshi",    "email": "[email protected]" }],  "variables": { "amount": "₹2,40,000" } }
{ "success": true, "data": {    "reference": "FV-2611-131",    "status": "sent", "is_test": true } }

The signer verifies and signs in FlowVerify’s signer app. Test code 000000.

Webhook→ your server

waiting
POST /flowverifyX-FV-Event-Type: envelope.completedX-FV-Signature: t=1794822127,v1=9c1f0e7a…{ "type": "envelope.completed",  "livemode": false,  "data": { "envelope": {      "reference": "FV-2611-131",      "status": "completed" } } }

Signature verified against the raw body. Your server answers 200.

01Build or call

What You Would Otherwise Build and Run

Signing looks like a PDF and a button until you list what sits behind it. On the left, the systems a team ends up owning. On the right, the call that replaces each one.

  1. Build it yourselfCertify every PDF and stamp each signature, so that a later change to the file shows.

    Call FlowVerifyOne POST. Sending certifies the document, and the signed PDF comes back through the same API with its certificate of completion.

  2. Build it yourselfDeliver one-time codes by email and SMS, and reminders on WhatsApp, with opt-outs handled.

    Call FlowVerifyauth on a recipient asks for a code by email or SMS. channels.whatsapp adds WhatsApp for the invite and reminders, and stops when the signer replies STOP.

  3. Build it yourselfIntegrate Aadhaar eSign through a licensed Certifying Authority, and keep that integration working.

    Call FlowVerifysigning_method: "aadhaar" on the envelope. The signer authenticates with an OTP on the mobile linked to their Aadhaar, and FlowVerify never stores the Aadhaar number.

  4. Build it yourselfWork out where the signature goes on every PDF your own system generates.

    Call FlowVerifyfields[].anchor quotes text printed on the page, and the field is placed beside the match.

  5. Build it yourselfMake every retry safe, so that a timeout never sends the same agreement twice.

    Call FlowVerifyAn Idempotency-Key on each create and send. The same key and body replay the first response for 24 hours.

  6. Build it yourselfPoll for status, or run a dispatcher of your own with signatures, retries and a delivery log.

    Call FlowVerifyenvelope.completed arrives as a signed webhook. A failed delivery is retried on a schedule, kept in a 30-day log and can be replayed.

  7. Build it yourselfBuild a signing screen, with identity checks, consent and an audit trail behind it.

    Call FlowVerifyA signing session opens FlowVerify’s signer app inside your product, by redirect or in a frame. Every check the sender set still runs.

  8. Build it yourselfStand up a sandbox that cannot email a real customer by mistake.

    Call FlowVerifyA key that starts with fv_test_. The endpoints, payloads and error codes are the same, and nobody is contacted.

02The integration

The Integration, Commit by Commit

A team adding signing to its own product merges five changes. Each one is shown as the code that lands in the repository, with what comes back when it runs.

  1. 1chore: add the FlowVerify client

    Start With a Test Key

    Once your workspace is set up, create a key in the Test environment under Developers, API keys. It runs the whole flow: documents are certified, statuses move and webhooks fire, while nobody is emailed, texted or messaged on WhatsApp and nothing is charged. Signers verify with the fixed code 000000.

    Test mode guide
    lib/flowverify.tsTypeScript
    import { FlowVerify } from '@flowverify/sdk';
    
    // FV_API_KEY is fv_test_… on laptops and in CI,
    // and fv_live_… in production. Nothing else changes.
    export const fv = new FlowVerify({ apiKey: process.env.FV_API_KEY! });
    
    const me = await fv.account.me();
    console.log(me.api_key.environment); // "test"
  2. 2feat: send the order form from a template

    Send From a Template, Exactly Once

    The template holds the document, the signing roles and the fields. Your call names the signer and fills the variables by name. The idempotency key is derived from your own order id, so a job that runs twice replays the first response and sends nothing new.

    SDK guide
    orders/send-order-form.tsTypeScript
    import { idempotencyKey } from '@flowverify/sdk';
    import { fv } from '../lib/flowverify';
    
    export const sendOrderForm = (order: Order) =>
      fv.templates.createEnvelope(
        process.env.FV_ORDER_FORM_TEMPLATE!,
        {
          reference: `order-${order.id}`,
          recipients: [{ role: 'signer_1', name: order.buyer, email: order.email }],
          variables: { amount: order.amount, delivery_by: order.deliveryBy },
        },
        { idempotencyKey: idempotencyKey('order', order.id) },
      );
  3. 3feat: sign contracts the billing system generates

    Place a Field by Quoting the Page

    A PDF your own system generates never has its signature block at the same coordinates. Quote the text printed beside it and the field lands next to it; when the text appears more than once, occurrence says which. If the page is still being read, the call answers 409 text_not_ready with a Retry-After.

    API reference
    contracts/send-rate-contract.tsTypeScript
    const draft = await fv.envelopes.create({ name, recipients: [signer] });
    const file = await fv.envelopes.addFile(draft.id, { file: pdf, fileName });
    const to = draft.recipients![0]!.id;
    
    // Quote the text printed beside each field. No coordinates.
    await fv.envelopes.addFields(draft.id, {
      fields: [
        { file_id: file.id, recipient_id: to, type: 'signature',
          anchor: { text: 'Authorised Signatory', placement: 'above' } },
        { file_id: file.id, recipient_id: to, type: 'date',
          anchor: { text: 'Date:', occurrence: 2 } },
      ],
    });
    await fv.envelopes.send(draft.id);
  4. 4feat: sign inside the customer portal

    Open Signing Inside Your App

    When the buyer clicks Sign, your server asks for a signing session and redirects to its URL. The URL opens once and lasts 15 minutes. The key needs the embedded:sign scope, the return address must be on your allowlist, and the signer still passes the one-time code and consent.

    Embedded signing guide
    routes/sign.tsTypeScript
    // The buyer clicked "Sign" in your portal.
    app.post('/orders/:id/sign', async (req, res) => {
      const order = await orders.get(req.params.id);
      const session = await fv.envelopes.createSigningSession(
        order.envelopeId,
        order.recipientId,
        { return_url: `https://portal.kiranexports.in/orders/${order.id}` },
      );
      res.redirect(303, session.url); // opens once, valid for 15 minutes
    });
  5. 5feat: mark the order signed

    Listen for the Webhook, Then Swap the Key

    constructEvent checks the signature over the raw body and rejects anything signed more than five minutes ago. Deliveries are at least once, so dedupe on the event id. Going live is a key swap: the endpoints, payloads and error codes are identical.

    Webhooks guide
    routes/webhooks.tsTypeScript
    app.post('/flowverify', express.raw({ type: 'application/json' }), (req, res) => {
      try {
        const event = constructEvent({
          rawBody: req.body,
          header: req.headers['x-fv-signature'],
          secret: process.env.FV_WEBHOOK_SECRET!,
        });
        if (event.type === 'envelope.completed') markOrderSigned(event);
        res.sendStatus(200);
      } catch (err) {
        if (err instanceof WebhookSignatureError) return res.sendStatus(400);
        throw err;
      }
    });
Developer Platform: the full API tour

The same five changes in Python use the flowverify package.

03Agents

Or Hand the Same Calls to an Agent

The MCP server turns the API into 23 tools for Claude, ChatGPT, Cursor or an agent you build. A mandate from an admin decides what that agent may do, and each action is recorded under its name.

  • Claude
  • ChatGPT
  • Cursor
  • Any MCP client
  1. 1API or MCP

    Connect a Client, or Your Own Agent

    A client that speaks MCP over Streamable HTTP connects with an API key in a header. Claude and ChatGPT connect as apps, after a FlowVerify sign-in. An agent you build can skip MCP and pass its mandate through the SDK. Each one gets what its scopes allow and no more.

    The MCP server
  2. 2Mandate

    An Admin Sets the Limits

    The mandate names the templates, the actions, the recipient domains, the sends per day and the expiry date, and can require a preview before every send. A call outside it is refused before anything is certified or emailed. Revoking the mandate stops the agent at once.

    Agent mandates
  3. 3Webhook on signed

    Signed, With the Agent on Record

    When the last signer signs, envelope.completed reaches your endpoint as it does for any send. The run log, the audit trail and the certificate of completion each name the agent, its mandate and the person who issued it.

    Evidence and verification

04What teams build

What Teams Wire It Into

Six integrations engineering teams ship first. Each one is named with the calls, scopes and events it uses, as they are spelt in the API.

  • Customer Agreements at Checkout

    The buyer signs inside your checkout or portal, in a session that opens once and lasts 15 minutes.

    • POST …/signing-session
    • embedded:sign
    • ?status=signed
  • Loan and Lending Agreements

    The borrower signs with Aadhaar eSign, using an OTP on the mobile linked to their Aadhaar. FlowVerify never stores the Aadhaar number.

    • signing_method: "aadhaar"
    • recipient.signed
  • Vendor Onboarding by a Procurement Agent

    An agent sends the vendor NDA and the purchase order from approved templates, to approved domains, under a daily cap.

    • X-Agent-Mandate
    • send_from_template
    • confirm: true
  • Offer Letters From an HR Bot

    Your bot fills the letter from the HR record and sends it once, however many times the job retries.

    • variables
    • Idempotency-Key
    • recipient.signed
  • Order Forms From a CRM

    A deal closes, the order form goes out and the signed PDF comes back to the deal. Zoho CRM, HubSpot and Salesforce have ready connectors, and Zapier reaches the rest.

    • POST /templates/{id}/envelopes
    • envelope.completed
    • GET …/download
  • Policy Acknowledgements in Bulk

    One draft becomes one envelope per person, each with its own signing link and audit trail. Up to 5,000 recipients in one request.

    • POST …/bulk-send
    • bulk_send.completed

05The run log

Every Agent Call, as Your Admin Sees It

The Agents console lists each call made under a mandate: what happened, which client made it, which mandate it used and how it ended. A refusal is a row like any other.

  • Client names and versions come from the MCP server, or from agentClient in the SDK
  • Filter by outcome, by mandate and by date range, and export the log as CSV
  • A refused call changes nothing and is counted on the mandate’s usage
  • An agent reads its own limits and today’s usage from GET /me before it acts
Run log listing each agent action with its agent, mandate and outcome
A real screen: the run log of the sample workspace, newest first. The fourth row is a send to an address at gmail.com, refused because that domain is outside the mandate.

07Before you ship it

What Your Security Review Will Ask

Short answers for the review that happens before a key reaches production.

  • Access

    Keys are scoped by resource and action, can be limited to your IP addresses and are shown once, after an admin confirms a one-time code. An id from another workspace answers 404. The console itself sits behind roles, single sign-on and two-factor.

    Developer Platform
  • Evidence

    Webhooks are signed with HMAC-SHA256 over a timestamp and the raw body, with a five-minute tolerance, and secrets rotate with a 24-hour overlap. Every envelope has an audit trail and a tamper-evident certificate of completion.

    Webhooks guide
  • AI controls

    An agent acts only inside its mandate, each call lands in the run log, and no API call or agent signs for anyone. Model features run only after an admin accepts the AI terms, each has its own switch, and India-only processing is available.

    Agent mandates
  • Deployment

    Shared cloud, or a dedicated single-tenant deployment for one organisation. AES-256 at rest and TLS in transit.

    Security

FAQ

Questions Engineering Teams Ask First

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

Yes. Once your workspace is set up, your developers create test keys themselves under Developers, API keys. A key that starts with fv_test_ creates test documents that never email, text, message on WhatsApp or charge anyone, while documents are still certified, statuses move and the certificate is produced. Webhooks carry livemode: false. Because no invitation goes out, you open the signing yourself with a signing session and enter the fixed code 000000. Aadhaar eSign is refused for test keys.

Nothing is sent twice. Every create and send takes an Idempotency-Key. The same key with the same body replays the first response for 24 hours, the same key with a different body is refused, and a request that is still running answers 409 so you can wait and retry. Both SDKs set a key on every such call and can derive one from your own record id.

No. The signer always signs in FlowVerify’s signer app, with the verification the sender chose. Your code can open that same flow inside your product with a signing session, and a workspace can sign with its own organisation certificate. Neither the API nor the MCP server has a call that signs for a third party.

Its mandate. An admin chooses the templates, the actions, the recipient domains, a daily send cap, a recipient limit and an expiry date, and can require a preview before every send. A request outside the mandate answers 403 mandate_limit_exceeded, names the limit and performs nothing. Through the MCP server, sending, reminding and voiding also need an explicit confirm. Revoking the mandate stops the agent at once.

Claude Code, Cursor, VS Code and any client that speaks MCP over Streamable HTTP and can send an Authorization header connect with an API key. Claude and ChatGPT connect as apps: a person signs in to FlowVerify, chooses the permissions, live or test mode and the mandate, and can disconnect the app later. Both routes reach the same tools and are held to the same limits.

Each delivery carries an X-FV-Signature header with a timestamp and an HMAC-SHA256 of the timestamp, a dot and the raw request body, keyed with the endpoint’s signing secret. Compare in constant time and reject timestamps older than five minutes. constructEvent in the TypeScript SDK and construct_event in the Python SDK do all of this. For 24 hours after a secret is rotated the header carries two signatures, and either one is accepted.

Book a demo

See Your Flow Run
on a Test Key

Bring the agreement your product sends, such as an order form or a loan agreement. We create a test key with you, send it from a template, sign it in an embedded session and watch the webhook arrive.

What you get

  • A test key and a first request, made together
  • Your flow mapped to endpoints, scopes and events
  • Answers from the people who build the API