Fill

Configure a form once, then fill it many times — from exact values, or drafted from your source documents.

View as Markdown

POST /v1/fill fills a form PDF and returns the completed file. Send exactly one of two inputs:

  • values — the field values to write, keyed by field name. Deterministic: no drafting pass, no model call.
  • files — source documents. CloudRaker drafts one value per field.

Fill works best as a two-step flow. Configure once: upload the blank form as a template, inspect its fields, curate them, and save the result on a fill config. Fill many times: call POST /v1/fill with action and either values or files. See Configure a form once.

How it works

  1. You pick the form. Send template inline — {"id": "…"} for a saved template, or {"url": "…"} for a one-off. Or send action naming a saved config that carries one. Inline wins when both are present.
  2. You pick the input. values writes your JSON straight into the form. files parses the sources and drafts a value per field. A fill run never re-detects fields: it uses the fields saved on the config, or the form’s own field inventory when none are saved.
  3. In files mode, CloudRaker writes the drafted values into the PDF.
  4. The completed file comes back as output.file. It is flattened (values baked in) or editable (still a fillable form).
  5. The run and its files expire on their own (ttl, 24 hours by default) unless you keep them.

Quickstart

The sample drafts a blank IRS Form W-9 from one source document. Both are public URLs. Nothing is local.

$curl -X POST https://api.cloudraker.com/v1/fill \
>  -H "Authorization: Bearer $CLOUDRAKER_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "template": { "url": "https://www.irs.gov/pub/irs-pdf/fw9.pdf", "name": "w9.pdf" },
>    "files": [{ "id": "a04d6597-4e34-4a99-94ea-964c289a4c68" }],
>    "instructions": "Use the legal entity name, not the trade name.",
>    "output": "flattened"
>  }'

The TypeScript and Python samples are plain HTTP, so they run with nothing installed. This endpoint is also a top-level method on both SDKs as of 0.3.0: client.fill(…). That page has a full worked example.

Example response

1{
2  "object": "fill_run",
3  "id": "flr_01KYD75GGJ8QK6HN2TVZ0ABCDE",
4  "status": "processed",
5  "expiresAt": "2026-07-26T18:03:41.512Z",
6  "statusUrl": "/v1/runs/flr_01KYD75GGJ8QK6HN2TVZ0ABCDE",
7  "files": [
8    { "id": "a04d6597-4e34-4a99-94ea-964c289a4c68", "name": "w9.pdf", "status": "processed" }
9  ],
10  "output": {
11    "file": {
12      "id": "6913da38-6d0c-4b6f-9a1e-2b0f6f2b8a41",
13      "name": "w9-template (filled).pdf",
14      "url": "https://cdn.cloudraker.com/…/latest?token=…"
15    },
16    "files": [
17      { "id": "6913da38-6d0c-4b6f-9a1e-2b0f6f2b8a41", "name": "w9-template (filled).pdf", "url": "https://cdn.cloudraker.com/…/latest?token=…" }
18    ],
19    "fields": { "topmostSubform[0].Page1[0].f1_01[0]": "Acme Manufacturing Co." }
20  }
21}

Key fields

FieldWhat it is
objectAlways fill_run.
idThe run id (flr_…).
statusqueued, processing, needs_input, processed, failed, cancelled, or expired.
files[]The source documents, with per-file status. In values mode, this holds a run-scoped copy of the template instead.
output.fileThe completed PDF: {id, name, url}. Also at GET /v1/runs/:id/output/:name.
output.fieldsThe values written into the form, keyed by the PDF’s own field names. Empty when the sources carried nothing for any field.

The output file’s bytes are registered a moment after the run reports processed. In that window, output.file can arrive without its url, and the /output/ alias can answer 404. Re-fetch GET /v1/runs/:id and the URL will be there.

Configure a form once

Curating a form once makes every later fill predictable. The saved fields fix the schema: field names, human labels, per-field guidance, and which fields to skip.

1

Save the blank form as a template

POST /v1/templates with a url, or the presigned-upload shape. See Templates.

2

Inspect it

POST /v1/templates/:id/inspect returns { fields, schema, pageBoxes, pageCount, detected, templateHash }. Each field carries name, type, label, page, and box. CloudRaker detects fields when the PDF has none of its own — detected says so. Templates over 32 MB answer 413 template_too_large.

3

Curate the fields

Rewrite each field’s label, add a description with filling guidance, and set ignore: true on fields no run should touch. Keep name, type, page, and box as returned.

4

Save fields and hash on a fill config

POST /v1/fill/configs with the curated fields and the templateHash from the same inspect. The hash lets you spot a stale curation after the template changes.

$curl -X POST https://api.cloudraker.com/v1/fill/configs \
>  -H "Authorization: Bearer $CLOUDRAKER_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "name": "Vendor onboarding",
>    "config": {
>      "template": "23e0a865-0be9-45b1-a491-f1b6bd58a31a",
>      "instructions": "Use the legal entity name, not the trade name.",
>      "output": "flattened",
>      "fields": [
>        {
>          "name": "topmostSubform[0].Page1[0].f1_01[0]",
>          "type": "text",
>          "label": "Legal entity name",
>          "description": "The registered legal name, never the trade name.",
>          "page": 0,
>          "box": { "x": 58.6, "y": 118.0, "width": 517.4, "height": 14 },
>          "ignore": false
>        }
>      ],
>      "templateHash": "9c56cc51b374c3ba189210d5b6d4bf57790d351c96c47c02190ecf1e430635ab"
>    }
>  }'

A fill config accepts exactly these keys: template (a template or file id), instructions, output, fields, and templateHash. An unknown key answers 400 instead of being stored dead. PATCH /v1/fill/configs/{idOrSlug} deep-merges the keys you send and keeps all other saved keys.

From then on, every call is one line of config:

$# deterministic — your values, no model call
$curl -X POST https://api.cloudraker.com/v1/fill \
>  -H "Authorization: Bearer $CLOUDRAKER_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{ "action": "vendor-onboarding", "values": { "topmostSubform[0].Page1[0].f1_01[0]": "Acme Manufacturing Co." } }'
$
$# drafted — values are drafted from the source documents
$curl -X POST https://api.cloudraker.com/v1/fill \
>  -H "Authorization: Bearer $CLOUDRAKER_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{ "action": "vendor-onboarding", "files": [{ "id": "a04d6597-4e34-4a99-94ea-964c289a4c68" }] }'

template is optional when action carries one — the saved template applies, and sending template inline still wins. Any other inline field also wins over its saved counterpart.

A fill run never re-inspects the form. Inspect runs at configure time only. A run uses the config’s saved fields; with none saved, it uses the form’s own field inventory and labels.

GET, PATCH and DELETE /v1/fill/configs/{idOrSlug} manage a config. GET /v1/fill/configs lists them. /v1/actions still works as a deprecated alias. See Saved configs.

Fill from values

values mode is deterministic. Your JSON is coerced to each field’s type and written into the PDF. No model is called.

Key values by field name — the names come from inspect, or from the fields saved on the config. Its schema describes the exact object values accepts.

A key that matches no field fails the run fast, before anything is written or metered. The run reports status: "failed" with error.code: "unknown_fields", and error.message lists the offending keys.

Configuration

FieldTypeWhat it does
template{id} or {url, name?}A saved template, or an ephemeral one fetched for this run only. Optional when action carries one; inline wins.
valuesobjectThe field values to write, keyed by field name. Send this or files, never both.
files[]array of {url, name?, processing?} or {id}, 1–100The documents the values are drafted from. Send this or values, never both.
instructionsstring, ≤ 4000 charsGuidance for the draft (“use the 2025 fiscal year figures”). files mode only.
outputflattened | editableflattened (default) bakes the values in. editable keeps the form fillable.
actionstringA saved config, by id or slug. Inline fields win over its saved config.
metadataobjectYour own key/values, echoed back on the run body (not on webhook deliveries). Max 10 KB.
webhook{url} or {id}Where to deliver terminal events. See Webhooks.
ttlinteger seconds, 1–604800How long the run and its files live. Default 24 hours, max 7 days.

An ephemeral template: {url} is fetched at run time. It is not added to your template library. The fetched copy is registered as a file in your API workspace. GET /v1/files lists it while the run is alive. But the copy belongs to the run: it is reclaimed when the run expires. POST /v1/runs/:id/keep moves it into the target space with everything else.

Pass {id} when you fill the same blank form repeatedly. A saved template is persistent. A run’s TTL never touches it.

Sync vs async

Synchronous by default, with ?wait= between 0 and 120 seconds, exactly like extract.

Next steps

Templates

Store a blank form once, inspect its fields, and fill it by id.

Sign

Send the completed document out for signature.

Runs

Statuses, downloading outputs, TTL, and keeping a result.

Webhooks

Get a notification when a run parks or finishes instead of polling.