Envelopes
Build an envelope from your own document, send it, follow it and download the signed result.
An envelope is the unit of sending: one or more files, the recipients who act on them, the fields each signer fills, and the settings (deadline, signing order, reminders). It moves through draft → sent → … → completed (or declined, expired, voided); the full state machine is described under status.
If your documents come from templates, the Templates guide is the shorter path. This page builds an envelope from scratch.
Create a draft
curl -X POST https://api.flowverify.co/v1/envelopes \
-H "Authorization: Bearer fv_live_xxxxxxxx" \
-H "Idempotency-Key: nda-4711-create" \
-H "Content-Type: application/json" \
-d '{
"name": "Mutual NDA — Acme × Globex",
"reference": "nda-4711",
"days_to_complete": 10,
"send_in_order": false,
"recipients": [
{ "name": "Asha Rao", "email": "[email protected]", "role": "sign", "order": 1 },
{ "name": "Legal Ops", "email": "[email protected]", "role": "copy" }
]
}'Recipient role is sign (signs), approve (approves before signers are notified) or copy (receives the finished document). reference is your correlation id and comes back as external_reference on every read. Optional settings: signing_method (flowverify default, aadhaar, pfx), expires_at (fixed deadline instead of days_to_complete), auto_reminders / reminder_days, note_to_recipients, folder, description.
Upload the document(s)
Three ways to add a file to a draft; PDF, DOCX, PPTX and RTF are accepted (non-PDF files are converted). Up to 25 MB per file.
curl -X POST https://api.flowverify.co/v1/envelopes/{id}/files \
-H "Authorization: Bearer fv_live_xxxxxxxx" \
-F "[email protected];type=application/pdf" \
-F "name=Mutual NDA"The response is the file object with its id and page_count; you need both to place fields. Files can be renamed (PATCH …/files/{fileId}) or removed (DELETE) while the envelope is a draft.
Place fields
Every signer needs at least one field. Positions are PDF points from the top-left corner of the page (x from the left, y from the top); US Letter is 612 × 792 pt, A4 is 595 × 842 pt. PUT replaces the whole set, POST appends.
curl -X PUT https://api.flowverify.co/v1/envelopes/{id}/fields \
-H "Authorization: Bearer fv_live_xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"fields": [
{ "file_id": "{fileId}", "recipient_id": "{ashaId}", "type": "signature", "page": 3, "x": 72, "y": 640, "width": 180, "height": 48 },
{ "file_id": "{fileId}", "recipient_id": "{ashaId}", "type": "date", "page": 3, "x": 300, "y": 640, "width": 120, "height": 28 },
{ "file_id": "{fileId}", "recipient_id": "{ashaId}", "type": "text", "label": "Designation", "page": 3, "x": 72, "y": 700, "width": 220, "height": 28, "required": false }
]
}'Field types: signature, initial, text, date, checkbox, email, dropdown and radio (with options), full_name, company, job_title, stamp, image. Only sign recipients may hold fields; approvers and copy recipients never do.
Send
curl -X POST https://api.flowverify.co/v1/envelopes/{id}/send \
-H "Authorization: Bearer fv_live_xxxxxxxx" \
-H "Idempotency-Key: nda-4711-send" \
-H "Content-Type: application/json" \
-d '{ "subject": "Please sign the NDA", "message": "Thanks for a quick turnaround.", "sender_name": "Acme Legal" }'Sending certifies the documents, emails the first signer (or all of them when send_in_order is false), starts the deadline and consumes one envelope of your monthly quota. It is refused when a signer has no fields (409 state_conflict, details.reason: "signer_without_fields"), when a template role is still unassigned, when a recipient uses an OTP option your plan lacks (403 feature_not_available) or when the quota is exhausted (403 plan_limit_exceeded). Always send with an Idempotency-Key — a retried send is replayed, never duplicated.
Recipients and verification
Add recipients to a draft with POST /envelopes/{id}/recipients, edit with PATCH …/recipients/{rid}, remove with DELETE. Per recipient you can require verification before signing:
{ "name": "Asha Rao", "email": "[email protected]", "role": "sign", "phone": "+919822071634", "auth": { "email_otp": true, "sms_otp": true } }Email OTP needs the Pro plan or higher, SMS OTP the Business plan or higher, Aadhaar eSign (signing_method: "aadhaar") the Business plan or higher. Phone numbers are E.164 (+14155552671, +919822071634).
Status and history
GET /envelopes/{id} returns the full object with recipients, files and fields. For polling use the lighter views:
GET /envelopes/{id}/status— progress percentage, signer counts by state, allowed actions (can_void,can_hold, …) and a timeline.GET /envelopes/{id}/history— the audit trail: every view, verification, signature and decline with actor and time.
| Envelope status | Meaning |
|---|---|
draft | Being prepared; editable |
sent, delivered | Sent; waiting for the first action |
viewed, in_progress, pending, signed | Recipients are acting; signed means some but not all signers finished |
completed | Every signer signed; documents certified; downloads available |
declined | A signer or approver declined; terminal |
expired | Deadline passed; terminal unless extended before expiry |
voided, cancelled | Cancelled by you; terminal |
on_hold | Paused with POST …/hold; resume with POST …/resume |
archived | Finished and archived |
failed | Certification or delivery failed; contact support with the request_id |
Recipient statuses: pending, sent, delivered, bounced, viewed, in_progress, signed, declined, delegated, cancelled.
Lifecycle actions
| Call | Effect |
|---|---|
POST /envelopes/{id}/remind | Re-sends the signing email to pending signers (optionally one recipient_id, custom message) |
POST /envelopes/{id}/void | Cancels a sent envelope (reason recommended); recipients are told |
POST /envelopes/{id}/hold / resume | Pause and continue an in-flight envelope |
POST /envelopes/{id}/archive | Archive a finished envelope |
PATCH /envelopes/{id} | Edit draft settings; after sending, only the deadline (days_to_complete / expires_at) can still be extended |
DELETE /envelopes/{id} | Delete a draft |
Downloads
| Call | Returns |
|---|---|
GET /envelopes/{id}/files/{fileId}/download | One PDF (the signed version once completed) |
GET /envelopes/{id}/download | ZIP with every file and the completion certificate |
GET /envelopes/{id}/certificate | The completion certificate PDF (409 until completed) |
Downloads stream through the API after the ownership check — there are no long-lived public links.
Listing
GET /envelopes?status=sent&limit=50&offset=0&sort=created_at&order=desc supports status, search (name or reference), from / to (created between), sort (created_at, updated_at, name, status, sent_at) and order. Results are workspace-wide, newest first.