Fill a form from source documents | CloudRaker documentation

curl -X POST https://api.cloudraker.com/v1/fill \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "template": {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
  },
  "files": [
    {
      "url": "https://example.com/documents/invoice_12345.pdf"
    }
  ]
}'

{
  "object": "fill_run",
  "id": "9b2f1e4a-3c4d-4f5a-8b7e-1a2c3d4e5f6a",
  "status": "queued",
  "expiresAt": "2024-07-01T12:00:00Z",
  "statusUrl": "https://api.cloudraker.com/v1/runs/9b2f1e4a-3c4d-4f5a-8b7e-1a2c3d4e5f6a/status",
  "files": [
    {
      "id": "a04d6597-4e34-4a99-94ea-964c289a4c68",
      "name": "invoice_12345.pdf",
      "status": "pending",
      "error": ""
    }
  ],
  "file": {
    "id": "b15d7f8e-9c3a-4d2b-8f7e-123456789abc",
    "name": "filled_form.pdf",
    "status": "pending",
    "error": ""
  },
  "error": {
    "code": "",
    "message": ""
  },
  "metadata": {},
  "tasks": [
    {
      "id": "task_001",
      "title": "Review filled form for invoice 12345",
      "url": "https://app.cloudraker.com/tasks/task_001"
    }
  ],
  "output": {
    "files": [
      {
        "id": "a04d6597-4e34-4a99-94ea-964c289a4c68",
        "name": "invoice_12345.pdf",
        "url": "https://cdn.cloudraker.com/uploads/a04d6597-4e34-4a99-94ea-964c289a4c68.pdf"
      }
    ],
    "file": {
      "id": "b15d7f8e-9c3a-4d2b-8f7e-123456789abc",
      "name": "filled_form.pdf",
      "url": "https://cdn.cloudraker.com/filled_forms/b15d7f8e-9c3a-4d2b-8f7e-123456789abc.pdf"
    },
    "fields": {}
  }
}

Drafts a form PDF’s field values from the supplied source documents and returns the completed file.

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.

Human review. review: "required" parks the run in needs_input with one task per document instead of finishing it. From there you can read the drafted values at GET /v1/runs/{id}/task, submit corrections to POST /v1/runs/{id}/task, or send a person to the ready-made page at tasks[].url.

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

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

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}`
Parked for a human	`202` right away, `status: "needs_input"` plus `tasks[]`

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

Drafts a form PDF's field values from the supplied source documents and returns the completed file. **Pick the form** with `template`, either shape: - `{ "id": "…" }` — a saved [template](https://docs.cloudraker.com/api/cloud-raker-api/templates/get-template), or any file you own. - `{ "url": "…" }` — fetched fresh for this run and purged with it. **Human review.** `review: "required"` parks the run in `needs_input` with one task per document instead of finishing it. From there you can read the drafted values at [GET /v1/runs/{id}/task](https://docs.cloudraker.com/api/cloud-raker-api/runs/get-run-task), submit corrections to [POST /v1/runs/{id}/task](https://docs.cloudraker.com/api/cloud-raker-api/runs/submit-run-task), or send a person to the ready-made page at `tasks[].url`. **Shape the output** with `output`: `flattened` (default) bakes the values in, `editable` leaves the form fillable. ```json { "files": [{ "id": "a04d6597-4e34-4a99-94ea-964c289a4c68" }], "template": { "id": "23e0a865-0be9-45b1-a491-f1b6bd58a31a" }, "review": "required" } ``` ### 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}` | | Parked for a human | `202` right away, `status: "needs_input"` plus `tasks[]` | <Note> The `202` is a graceful degrade, never an error — poll [the run](https://docs.cloudraker.com/api/cloud-raker-api/runs/get-run) or wait for a [webhook](https://docs.cloudraker.com/api/cloud-raker-api/webhooks/create-webhook-endpoint). Replaying an `idempotency-key` returns the original run alongside an `idempotent-replay: true` response header. </Note> **Learn more:** [Form filling guide](https://docs.cloudraker.com/capabilities/fill)

Authentication

AuthorizationBearer

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

Query parameters

waitintegerOptional0-120Defaults to 60

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

Defaults to 60, maximum 120. 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.

How many seconds to hold the request open waiting for the run to finish. Defaults to `60`, maximum `120`. 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.

templateobjectRequired

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.

fileslist of objectsRequired

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.

reviewenumOptional

Whether a person checks the drafted values before the form is produced.

none (the default) fills and finishes. required parks the run at needs_input with one task per document — read it at GET /v1/runs/{id}/task, submit corrections to POST /v1/runs/{id}/task, or send someone to the ready-made page at tasks[].url.

outputenumOptional

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

actionstringOptional>=1 character

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

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-604800

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

Defaults to 24 hours; 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`	Parked for a person — see `tasks[]`
`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

fileobject

errorobject

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 any

taskslist of objects

The human steps currently blocking the run. Present while status is needs_input.

Each task has a url — a ready-made page you can send a person to — or you can drive it yourself through GET and POST /v1/runs/{id}/task. E-signature runs never carry tasks[]: their signing links are signer-held secrets, so use envelopeUrl instead.

outputobject

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

Drafts a form PDF’s field values from the supplied source documents and returns the completed file.

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.

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

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

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}`
Parked for a human	`202` right away, `status: "needs_input"` plus `tasks[]`

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

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