FlowVerifyDevelopers

Templates

Reuse documents, roles and field layouts, and send an envelope in one call.

A template is prepared once in the dashboard: the document(s), the roles (placeholders such as "Signer 1" or "HR Manager") and the fields each role fills. The API reads templates and turns them into envelopes; template authoring stays in the dashboard for now.

Read a template

curl https://api.flowverify.co/v1/templates?status=active&search=offer \
  -H "Authorization: Bearer fv_live_xxxxxxxx"
curl https://api.flowverify.co/v1/templates/{id} -H "Authorization: Bearer fv_live_xxxxxxxx"
{
  "success": true,
  "data": {
    "object": "template",
    "id": "…",
    "name": "Offer letter",
    "status": "active",
    "default_days_to_complete": 10,
    "current_version": { "object": "template_version", "id": "…", "number": 3, "page_count": 2, "ready": true },
    "roles": [
      { "object": "template_role", "key": "signer_1", "name": "Employee", "type": "signer", "order": 1, "required": true },
      { "object": "template_role", "key": "hr", "name": "HR Manager", "type": "signer", "order": 2, "required": true },
      { "object": "template_role", "key": "cc_finance", "name": "Finance", "type": "cc", "required": false }
    ],
    "fields": [
      { "object": "template_field", "id": "f_customer_name", "role": "signer_1", "type": "text", "label": "Full name", "page": 1, "prefillable": true },
      { "object": "template_field", "id": "f_sig", "role": "signer_1", "type": "signature", "page": 2, "prefillable": false }
    ]
  }
}

Two things matter for sending: roles[].key (or roles[].name) to assign recipients, and fields[].id for prefill. current_version.ready is false while a freshly uploaded document is still being converted.

Create an envelope from a template

curl -X POST https://api.flowverify.co/v1/templates/{id}/envelopes \
  -H "Authorization: Bearer fv_live_xxxxxxxx" \
  -H "Idempotency-Key: offer-2026-0912" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Offer letter — Asha Rao",
    "reference": "HR-2026-0912",
    "recipients": [
      { "role": "signer_1", "name": "Asha Rao", "email": "[email protected]", "auth": { "email_otp": true } },
      { "role": "HR Manager", "name": "Ravi Kumar", "email": "[email protected]" }
    ],
    "prefill": [
      { "field_id": "f_customer_name", "value": "Asha Rao" }
    ],
    "days_to_complete": 7,
    "subject": "Your offer letter is ready to sign",
    "sender_name": "Acme People Ops"
  }'

What happens:

  1. The template's current version (or version_id) is cloned into a new envelope: files, fields and one recipient per role.
  2. Each recipient you pass replaces the placeholder of the role named by role — the role key (signer_1) or its display name (HR Manager, case-insensitive). Unknown or duplicate roles answer 400 validation_failed naming the offending recipients[i].role.
  3. prefill writes values into text-like fields by template field id (text, date, checkbox, email, dropdown, radio, full_name, company, job_title). Signature and initial fields cannot be prefilled.
  4. Settings from the body (name, reference, days_to_complete, expires_at, send_in_order, auto_reminders, reminder_days, note_to_recipients, …) are applied on top of the template defaults.
  5. Unless send is false, the envelope is sent. Required roles must all have a recipient (400 validation_failed, details.errors[].role lists the missing ones); placeholders of unassigned optional roles are removed so nobody receives a bounce.

The response is the envelope (201) plus sent: true|false.

Drafts

Pass "send": false to get a draft back. Roles you did not assign keep a placeholder recipient (recognisable by its @template.local address); replace each one with PATCH /envelopes/{id}/recipients/{rid} and send with POST /envelopes/{id}/send. Sending with a placeholder still in place is refused (409 state_conflict, details.reason: "template_role_unassigned").

If sending fails after the draft was created

Checks that run at send time (a verification option your plan does not include, an exhausted quota) can fail after the draft exists. The error then carries details.envelope_id; fix the draft and call POST /envelopes/{id}/send, or delete it.

Idempotency

Send-from-template is the call you least want to run twice. Use an Idempotency-Key derived from your own record (the order id, the employee id + date): a retried request with the same key and body replays the first response; the same key with a different body answers 422 idempotency_mismatch.

On this page