Fill a form from values or source documents

{
  "object": "string",
  "id": "string",
  "status": "queued",
  "expiresAt": "string",
  "statusUrl": "string",
  "files": [
    {
      "id": "string",
      "name": "string",
      "status": "string",
      "error": "string"
    }
  ],
  "file": {
    "id": "string",
    "name": "string",
    "status": "string",
    "error": "string"
  },
  "error": {
    "code": "string",
    "message": "string"
  },
  "metadata": {},
  "output": {
    "files": [
      {
        "id": "string",
        "name": "string",
        "url": "string"
      }
    ],
    "file": {
      "id": "string",
      "name": "string",
      "url": "string"
    },
    "fields": {}
  }
}

Fills a form PDF and returns the completed file. Send exactly one of values or files:

values — the field values to write, keyed by field name. Deterministic: no drafting pass, no model call.
files — source documents the field values are drafted from.

Pick the form with template, either shape:

{ "id": "…" } — a saved template, or any file you own.
{ "url": "…" } — fetched fresh for this run and purged with it.

template is optional when action names a saved config that carries one; sending it inline still wins.

Shape the output with output: flattened (default) bakes the values in, editable leaves the form fillable.

{
  "files": [{ "id": "a04d6597-4e34-4a99-94ea-964c289a4c68" }],
  "template": { "id": "23e0a865-0be9-45b1-a491-f1b6bd58a31a" }
}

Waiting for the result

Sync by default: the call holds open until the run finishes, up to ?wait= seconds (default 60, max 120, 0 returns immediately).

Outcome	Response
Finished inside the window	`200` with the full run
Still running at the cap	`202` with `{object, id, status, statusUrl}`

The 202 is a graceful degrade, never an error — poll the run or wait for a webhook. Replaying an idempotency-key returns the original run alongside an idempotent-replay: true response header.

Learn more: Form filling 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.

templateobjectOptional

The blank form to fill, given one of two ways.

{ "id": "…" } — a saved template from POST /v1/templates, or any file you own.
{ "url": "…", "name"?: "…" } — fetched for this run only and purged with it.

Optional when action names a saved config that carries one — sending it inline still wins.

instructionsstringOptional<=4000 characters

Free-form guidance for the drafting pass — which source document wins a conflict, how to format dates, which fields to leave blank.

outputenumOptional

What the produced PDF looks like. flattened (the default) bakes the values in so nothing can be changed; editable leaves the form fillable.

Allowed values:

actionstringOptional>=1 character

A saved fill action to run, by id or slug. Config you send inline is merged over the saved config.

fileslist of objectsOptional

The source documents the field values are drafted from, up to 100. Send this or values, never both.

valuesmap from strings to anyOptional

The field values to write, keyed by field name — deterministic, no drafting pass. Send this or files, never both.

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"fill_run"

idstring

statusenum

Where the run is in its life.

Status	Meaning
`queued`	Accepted, not started
`processing`	Work in flight
`needs_input`	Waiting for an external action, such as an e-signature
`processed`	Finished; `output` is populated
`failed`	Finished unsuccessfully
`cancelled`	Stopped on request
`expired`	TTL elapsed and the data was purged

The last four are terminal.

expiresAtstring or null

statusUrlstring

fileslist of objects

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 completed form. Present once status is processed.

file is the filled PDF with a signed download link; fields reports the values that were written into it, keyed by field name.

Errors

400

Bad Request Error

422

Unprocessable Entity Error

429

Too Many Requests Error