Concepts
The objects you work with, how they relate, and what a recipient experiences when you send something.
Objects
| Object | What it is | Where it lives |
|---|---|---|
| Workspace | Your FlowVerify organization. Every API key, envelope, template and webhook belongs to exactly one workspace; the API never shows you anything from another | GET /me |
| API key | A bearer credential with scopes. Actions taken with a key appear in audit trails as API (with the key's id), not as a person | Dashboard → Settings → Developers → API keys |
| Envelope | The unit of sending: files + recipients + fields + settings, with one lifecycle status | /envelopes |
| File | A document inside an envelope (PDF, or converted to PDF from DOCX/PPTX/RTF). Fields are positioned on a file's pages | /envelopes/{id}/files |
| Recipient | A 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 |
| Field | Something a signer fills or signs at a position on a page: signature, initials, date, text, checkbox, dropdown, … | /envelopes/{id}/fields |
| Template | A 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 job | One draft fanned out into many envelopes, one per recipient, sharing a bulk_group_id | /envelopes/{id}/bulk-send, /bulk-send-jobs |
| Webhook | An 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_orderis 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,voidedandcancelled. 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
| Role | Behaviour |
|---|---|
sign | Receives a signing link, fills their fields and signs. Needs at least one field |
approve | Approves or rejects the envelope before signers are notified; holds no fields |
copy | Receives 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
- 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. - If you required verification, the recipient enters the one-time code sent by email or SMS.
- The document opens in the FlowVerify signer with the fields you placed. Required fields must be completed; consent to sign electronically is captured.
- On finishing, the recipient sees a confirmation and, once everyone has signed, receives the completed document. Your envelope moves to
completedandenvelope.completedfires.
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 withreferencewhen creating or updating an envelope and returned on every read and in webhook payloads.request_id— unique per API call (X-Request-Idheader and in every JSON body); quote it when contacting support.