FlowVerifyDevelopers

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 statusMeaning
draftBeing prepared; editable
sent, deliveredSent; waiting for the first action
viewed, in_progress, pending, signedRecipients are acting; signed means some but not all signers finished
completedEvery signer signed; documents certified; downloads available
declinedA signer or approver declined; terminal
expiredDeadline passed; terminal unless extended before expiry
voided, cancelledCancelled by you; terminal
on_holdPaused with POST …/hold; resume with POST …/resume
archivedFinished and archived
failedCertification or delivery failed; contact support with the request_id

Recipient statuses: pending, sent, delivered, bounced, viewed, in_progress, signed, declined, delegated, cancelled.

Lifecycle actions

CallEffect
POST /envelopes/{id}/remindRe-sends the signing email to pending signers (optionally one recipient_id, custom message)
POST /envelopes/{id}/voidCancels a sent envelope (reason recommended); recipients are told
POST /envelopes/{id}/hold / resumePause and continue an in-flight envelope
POST /envelopes/{id}/archiveArchive 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

CallReturns
GET /envelopes/{id}/files/{fileId}/downloadOne PDF (the signed version once completed)
GET /envelopes/{id}/downloadZIP with every file and the completion certificate
GET /envelopes/{id}/certificateThe 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.

On this page