Fill from context docs

The fastest way to fill a form is to hand Emboss a PDF plus a context blob — a JSON object describing the subject of the form. Emboss detects the fields, matches them against your context, and fills what it can. This is the POST /forms/with-context endpoint, run as an asynchronous job.

Submit the form and context

The request is multipart/form-data with two parts: the file (the flat PDF) and a context field holding a JSON string.

curl -X POST https://api.getemboss.ai/forms/with-context \
  -H "Authorization: Bearer sk_live_yourkey" \
  -F "file=@./vendor-onboarding.pdf" \
  -F 'context={
        "legal_name": "Analytical Engines LLC",
        "contact": "Ada Lovelace",
        "email": "ada@analyticalengines.example",
        "ein": "12-3456789",
        "address": "5 Babbage Way, London"
      }'

{ "job_id": "job_8f2c", "status": "queued" }

The context is free-form. Use whatever keys describe your subject — Emboss maps them to the detected field labels semantically, so legal_name will find a "Business name" field.

Poll for the result

curl https://api.getemboss.ai/forms/with-context/job_8f2c \
  -H "Authorization: Bearer sk_live_yourkey"

While running, status is queued or running. When complete it is done with a session_id and a report; on failure it is error with an error message.

{
  "status": "done",
  "session_id": "sess_a1b2",
  "report": "Filled 9 of 11 fields. Left unfilled: signature, date.",
  "error": null
}

Download the filled PDF

The session_id points at a fully resolved session. Render and download it:

curl https://api.getemboss.ai/sessions/sess_a1b2/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.