Fill from your data

When you already have the values — from your database, a form your user filled, wherever — fill the PDF directly. No inference: you map each value onto a field by its id, and Emboss writes exactly that. (If instead you want Emboss to read the values out of documents, see Fill from context docs.)

1. Create the form and wait for detection

Upload the flat PDF, then poll until it's ready (see Tracking jobs):

curl -X POST https://api.getemboss.ai/forms \
  -H "Authorization: Bearer sk_live_yourkey" \
  -F "file=@./w9.pdf"

2. Read the contract to find field ids

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

Each field has an integer id — that's what you'll target. See The contract shape.

3. Open a session

curl -X POST https://api.getemboss.ai/sessions \
  -H "Authorization: Bearer sk_live_yourkey" \
  -H "Content-Type: application/json" \
  -d '{ "form_id": "6c47f7f5-f921-4698-910f-95dd7d81310b" }'

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

4. Write your values

PUT /sessions/{sid}/fields with a list of field_id → value updates:

curl -X PUT https://api.getemboss.ai/sessions/a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d/fields \
  -H "Authorization: Bearer sk_live_yourkey" \
  -H "Content-Type: application/json" \
  -d '{ "updates": [
        { "field_id": 1, "value": "Analytical Engines LLC" },
        { "field_id": 3, "value": "12-3456789" }
      ] }'

{ "session_id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "applied": [1, 3] }

An unknown field_id or a value the field won't accept returns 422.

5. Fill and download

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

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

That's the whole deterministic path — no guessing, just the values you provided.