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:
- The template's current version (or
version_id) is cloned into a new envelope: files, fields and one recipient per role. - 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 answer400 validation_failednaming the offendingrecipients[i].role. prefillwrites 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.- 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. - Unless
sendisfalse, the envelope is sent. Required roles must all have a recipient (400 validation_failed,details.errors[].rolelists 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.