Start an envelope
A draft: from a template (its documents, roles and steps, as Start from a template does), or empty with a title. Who is in it, the message and sending follow with the calls below. Send an Idempotency-Key: the same key returns the same answer for 24 hours.
bearerAuthorizationBearer <token>An access token from /v1/auth/token, or a personal token: opaque, beginning s2a_.
workspace_id*stringwsp_…, from GET /v1/me
length <= 40idempotency-key*stringA UUID of your own (ADR 0071 §5)
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$uuidapplication/json- body
template_id?stringtpl_…
length <= 40title?string1 <= length <= 200external_id?stringYour own reference (a ticket key, a CRM ID): unique in the workspace, in every webhook payload, never shown to recipients
length <= 255The new draft
application/json- response
The new draft
id*stringenv_…
reference*stringtitle*stringstatus*stringsubject*string|nullmessage*string|nulltemplate_id*|tpl_…, when made from one
external_id?stringYour own reference for it, unique in the workspace; left out when not set
documents*array<>recipients*array<>reference_values*The document type’s details, by field key (GET /document-types); sensitive ones are left out
withheld*array<string>The keys of details that are set but sensitive, so never returned
settings*Reminders, expiry and a scheduled send (SPEC 6.6)
created_at*string^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$date-timesubmitted_at*|When it was submitted; null until then
sent_at*|When it was sent; null until then
completed_at*|When it was completed; null until then
web_url*stringcurl -X POST 'https://api.sign2approve.com/v1/workspaces/string/envelopes' \ -H 'idempotency-key: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \ -H 'Content-Type: application/json' \ -d '{}'{ "id": "env_01a16d3fd3507be78e41c4540aa20a3c", "reference": "QUO-0042", "title": "Quote for Acme", "status": "draft", "subject": null, "message": null, "template_id": null, "documents": [ { "id": "doc_01a16d3fd3507be78e41c4540aa20a3d", "name": "Quote", "pages": 2, "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" } ], "recipients": [ { "id": "rcp_01a16d3fd3507be78e41c4540aa20a3e", "role_key": "client_signer", "name": "Pat Client", "email": "pat@client.example", "role": "signer", "kind": "external", "routing_order": 1, "status": "pending" } ], "reference_values": { "value": 14500 }, "settings": { "reminders": { "enabled": true, "first_after_days": 3, "every_days": 3, "max": 3 }, "expiry_days": 30, "expiry_warning_days": 3, "scheduled_send_at": null, "require_verification_code": false }, "created_at": "2026-10-24T09:00:00Z", "submitted_at": null, "sent_at": null, "completed_at": null, "web_url": "https://app.example.test/w/larkspur/envelopes/01a16d3f-d350-7be7-8e41-c4540aa20a3c"}