Fill from context docs

Hand Emboss a form plus one or more supporting documents — prior filings, a profile sheet, anything that holds the values — and it reads your documents and fills what it can match.

The default is filling a form you've already created: you ran detection once, and now you want to fill that same form from context. There's also a convenience path that takes a brand-new flat PDF and extracts and fills it in a single call.

Already have the values as structured data? Use direct fill instead (Fill from your data) — it's deterministic and skips the inference step.

Fill an existing form

If you've already created a form (see the Quickstart or POST /forms) and it's ready, fill it from context with POST /forms/{form_id}/with-context. The form is identified by {form_id} in the URL, so the request body carries only context file parts — no file.

curl -X POST https://api.getemboss.ai/forms/6c47f7f5-f921-4698-910f-95dd7d81310b/with-context \
  -H "Authorization: Bearer sk_live_yourkey" \
  -F "context=@./w9-prior-year.pdf" \
  -F "context=@./company-profile.txt"

{ "job_id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "status": "processing" }

This bills a single context fill. The form must be ready and owned by your key — an unready form returns 409, and one you don't own returns 404. Then poll the job below.

Start from a brand-new PDF

If you don't have a form yet, POST /forms/with-context takes the flat PDF and the context in one shot: Emboss detects the form's fields and fills them. The request is multipart/form-data — the file (the flat PDF) plus one or more context file parts.

curl -X POST https://api.getemboss.ai/forms/with-context \
  -H "Authorization: Bearer sk_live_yourkey" \
  -F "file=@./vendor-onboarding.pdf" \
  -F "context=@./w9-prior-year.pdf" \
  -F "context=@./company-profile.txt"

{ "job_id": "6c47f7f5-f921-4698-910f-95dd7d81310b", "status": "processing" }

Because this both extracts and fills, it bills an extraction plus a context fill. A non-PDF form returns 400.

Either way, limits per request are: up to 5 context files, 10 MB per file, 30 MB total, and 100 pages on the form — past these you'll get a 413. Going over the free tier with no card on file returns 402.

Poll for the result

Both endpoints return a job_id you poll the same way:

curl https://api.getemboss.ai/forms/with-context/6c47f7f5-f921-4698-910f-95dd7d81310b \
  -H "Authorization: Bearer sk_live_yourkey"

While running, status is processing. When it's ready you get a session_id; on failure it's failed with an error message.

{
  "job_id": "6c47f7f5-f921-4698-910f-95dd7d81310b",
  "status": "ready",
  "session_id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "error": null
}

The resulting session is already completed — use it to render and download, not to edit further. (PUT /sessions/{sid}/fields on a completed session returns 409.)

Download the filled PDF

curl https://api.getemboss.ai/sessions/a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d/pdf \
  -H "Authorization: Bearer sk_live_yourkey" \
  -o filled.pdf

Want to see what Emboss detected before or after the fill? Read the contract shape.