FlowVerifyDevelopers

Concepts

The objects you work with, how they relate, and what a recipient experiences when you send something.

Objects

ObjectWhat it isWhere it lives
WorkspaceYour FlowVerify organization. Every API key, envelope, template and webhook belongs to exactly one workspace; the API never shows you anything from anotherGET /me
API keyA bearer credential with scopes. Actions taken with a key appear in audit trails as API (with the key's id), not as a personDashboard → Settings → Developers → API keys
EnvelopeThe unit of sending: files + recipients + fields + settings, with one lifecycle status/envelopes
FileA document inside an envelope (PDF, or converted to PDF from DOCX/PPTX/RTF). Fields are positioned on a file's pages/envelopes/{id}/files
RecipientA person who acts on the envelope: sign, approve or copy. Each has an order, optional verification (email/SMS one-time code) and its own status/envelopes/{id}/recipients
FieldSomething a signer fills or signs at a position on a page: signature, initials, date, text, checkbox, dropdown, …/envelopes/{id}/fields
TemplateA reusable document with roles instead of people and fields already placed. Creating an envelope from a template assigns real recipients to the roles/templates
Bulk send jobOne draft fanned out into many envelopes, one per recipient, sharing a bulk_group_id/envelopes/{id}/bulk-send, /bulk-send-jobs
WebhookAn HTTPS endpoint subscribed to event types; each attempt to reach it is a delivery with its own status and retry schedule/webhooks

Envelope lifecycle

draft ──send──▶ sent ─▶ delivered ─▶ viewed ─▶ in_progress ─▶ signed ─▶ completed
                 │                                            (some signers done)
                 ├──▶ declined      (a signer or approver declined)
                 ├──▶ expired       (deadline passed)
                 ├──▶ voided        (you cancelled it)
                 └──▶ on_hold ⇄     (paused / resumed by you)
  • A draft is fully editable: files, recipients, fields and settings can change; nothing has been emailed.
  • Sending freezes the documents, emails the first signer (or all signers when send_in_order is false), starts the deadline and consumes one envelope of your monthly quota.
  • Completed means every signer has signed. Signed files and the Certificate of Completion are downloadable from then on.
  • Terminal states are completed, declined, expired, voided and cancelled. After sending, only the deadline can still be changed.

Every transition is also an event you can subscribe to — see Webhooks and the event reference.

Recipients

RoleBehaviour
signReceives a signing link, fills their fields and signs. Needs at least one field
approveApproves or rejects the envelope before signers are notified; holds no fields
copyReceives the completed documents; takes no action

With send_in_order: true recipients are notified one after another by order; otherwise all signers are notified at once. Per recipient you can require a one-time code by email or SMS before they can open the document, and the envelope's signing_method selects click-to-sign (flowverify), Aadhaar eSign (aadhaar) or your workspace's own certificate (pfx).

Recipient statuses: pending → sent → delivered → viewed → in_progress → signed; or declined, delegated (they handed it to someone else), bounced, cancelled.

What a recipient experiences

  1. An email from FlowVerify with the subject and message you passed (or defaults) and a Review & sign button. Your sender_name (or your workspace name) appears as the sender.
  2. If you required verification, the recipient enters the one-time code sent by email or SMS.
  3. The document opens in the FlowVerify signer with the fields you placed. Required fields must be completed; consent to sign electronically is captured.
  4. On finishing, the recipient sees a confirmation and, once everyone has signed, receives the completed document. Your envelope moves to completed and envelope.completed fires.

Signing always happens in the FlowVerify signer app: identity verification, consent and the tamper-evident audit trail are what make the signature hold up, so there is deliberately no API call that signs on someone else's behalf.

Fields and coordinates

Fields are placed per page in PDF points measured from the top-left corner: x grows to the right, y grows downward, width and height are in points. A US Letter page is 612 × 792 pt, A4 is 595 × 842 pt. Templates carry field positions for you; when you build envelopes from scratch, read page_count from the uploaded file and place fields with PUT /envelopes/{id}/fields.

Identifiers

  • id — UUID of any object.
  • reference — the short human-readable envelope id shown in emails and the dashboard (FV-…).
  • external_reference — your own correlation id, set with reference when creating or updating an envelope and returned on every read and in webhook payloads.
  • request_id — unique per API call (X-Request-Id header and in every JSON body); quote it when contacting support.

On this page