Skip to navigation

Collect e-signatures on a document

View as Markdown

Sends a PDF out for signature and tracks the envelope until every required signing slot is complete.

Each signer verifies their email with a one-time code and signs by typing their name. The completed document gets a signature certificate and a tamper-evident cryptographic seal, and comes back as a new file alongside output.auditUrl.

Where the signatures land — placement:

  • page (default) — a signature certificate page is appended to the document.
  • tags — each required signing slot replaces a [Signature N] placeholder. Optional initials and date tags use the same slot number.

Signing steps — routingOrder defaults to 1 (parallel signing). Later steps wait. People with the same signingGroup share one fieldIndex slot; the first to sign completes it.

Keeping others in the loop — cc: informed-only recipients who do not sign. They receive no OTP or signature tag, and are emailed the sealed document when the envelope completes.

Language — language: en (default) or fr. Sets the language of every recipient-facing asset — invitation and code emails, the signing page, and the audit certificate — for all signers and CC parties.

Always asynchronous. The call returns 202 with status: "needs_input" as soon as the envelope exists, and stays there until every required signing slot completes.

Managing the envelope — every sign response, both the 202 and the run, carries envelopeUrl:

{
"file": { "id": "a04d6597-4e34-4a99-94ea-964c289a4c68" },
"signers": [{ "name": "Ada Lovelace", "email": "ada@example.com" }],
"cc": [{ "name": "Charles Babbage", "email": "charles@example.com" }],
"message": "Please countersign by Friday.",
"placement": "page",
"language": "en"
}

Sign runs are exempt from the run TTL, so an envelope outlives the 7-day maximum and waits for its signers. Signing links are signer-held secrets and never appear on the sender’s API.

Learn more: E-signature guide

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

spaceIdstringRequired

Query parameters

waitintegerOptional0-120Defaults to 60

How many seconds to hold the request open waiting for the run to finish.

Finishing inside the window returns 200 with the full run; running past it returns 202 with a statusUrl to poll. Send 0 to skip waiting entirely and always get the 202.

Request

This endpoint expects an object.
signerslist of objectsRequired

Who can sign — up to 50 people, each with a name and an email. Omitted routingOrder means everyone signs in parallel. Set increasing steps for ordered signing; use a shared signingGroup for any-one signing.

Every signer verifies their email with a one-time code, then signs by typing their name. Track them individually at GET /v1/runs/{id}/envelope.

fileobjectRequired

An input file, given one of two ways.

  • { "url": "…", "name"?: "…", "processing"?: "…" } — fetched over http(s) for this run and purged with it.
  • { "id": "…" } — a file you already registered with POST /v1/files, reusable across runs and never re-parsed.
  • { "id": "…", "ephemeral": true } — a file you uploaded only for this run, purged with it. Use it only on a file no other run uses.
expiresInDaysintegerOptional1-90Defaults to 7

Days recipients have to complete signing, measured from dispatch. From 1 to 90; defaults to 7.

templateIdstringOptional>=1 character

Identifies the template your org signs delegated envelopes from. Consent is granted per template, so this is the scope the signer agrees to. A document produced by POST /v1/compose or POST /v1/fill carries its template sealed inside it and that value is used; this field is then ignored. Send it only for a delegated envelope whose document has no sealed template. Ignored when no signer is delegated.

templateNamestringOptional1-200 characters

Human-readable name of that template. Shown to the signer when their consent is requested, and printed on the audit page of every document signed under it. Like templateId, the value sealed into a composed or filled document wins. Required when any signers[] entry has delegated: true and the document carries no sealed template name: either the document has no seal, or its seal has no name. In the second case, also send the sealed templateId, or the run fails. Ignored otherwise.

messagestringOptional<=2000 characters
A note included in the invitation email each signer receives.
placementenumOptionalDefaults to page

Where signatures land in the document.

page appends a signature certificate page. tags replaces [Signature N] placeholders for each required signing slot. Optional [Initials N] and [Date N] tags add initials and signing dates. Any-one groups share their fieldIndex slot.

Allowed values:
cclist of objectsOptional

Informed-only recipients. CC parties do not sign, receive no OTP or signature tag, and are emailed the sealed document when the envelope completes.

languageenumOptionalDefaults to en

Language of every recipient-facing asset — invitation and code emails, the signing page, and the audit certificate. Applies to all signers and CC parties. Defaults to en.

Allowed values:
metadatamap from strings to anyOptional

Arbitrary JSON you attach to the run and get back on every read of it.

Use it to carry your own identifiers — an order number, a customer id — so a webhook or a polled run reconciles without a lookup table. Capped at 10 KB serialized.

webhookobjectOptional

Where to deliver this run’s events, given one of two ways.

  • { "url": "…" } — a one-off https endpoint for this run only.
  • { "id": "whe_…" } — a saved endpoint from POST /v1/webhooks. Runs hold the reference, so pausing or re-pointing that endpoint applies to this run too.

Deliveries are at-least-once and signed — dedupe on eventId and verify against GET /v1/webhooks/jwks.json.

ttlintegerOptional1-604800Defaults to 86400

How long, in seconds, to keep this run and its files before purging them automatically.

The maximum is 604800 (7 days). The deadline comes back as expiresAt on every read of the run. Call POST /v1/runs/{id}/keep before then to clear the TTL and move the results into a space permanently.

E-signature runs are exempt — an envelope waits for its signers however long that takes.

Response

The finished run.
object"sign_run"
idstring
statusenum

Where the run is in its life.

StatusMeaning
queuedAccepted, not started
processingWork in flight
needs_inputWaiting for an external action, such as an e-signature
processedFinished; output is populated
failedFinished unsuccessfully
cancelledStopped on request
expiredTTL elapsed and the data was purged

The last four are terminal.

expiresAtstring or null
statusUrlstring
fileslist of objects
envelopeUrlstring
fileobjectOptional
errorobjectOptional

Why the run failed. Present whenever status is failed, and only then.

code is the stable, snake_case reason (input_unavailable, parse_failed, …); message is the human-readable detail. Per-file and per-step failures are also reported in files[].error and, for a pipeline, steps[].error.

metadatamap from strings to anyOptional
outputobjectOptional

The signed document. Present once every required signing slot has completed.

file is the sealed PDF, signers[] records who signed and when, and auditUrl points at the machine-readable audit trail.

Errors

400
Bad Request Error
422
Unprocessable Entity Error
429
Too Many Requests Error