docs

How Emboss works

Emboss takes a flat PDF and gives you a filled one. Under the hood it runs a short pipeline:

  1. Detect — Emboss reads each page of your PDF and finds the fields: their labels, types, and positions.
  2. Contract — those fields become a structured JSON contract — the map of everything on the form. See The contract shape.
  3. Fill — you supply values and Emboss writes them into the right fields, either from data you already have or from documents you upload.
  4. Render — Emboss produces the finished, filled PDF for download.

It's asynchronous

Detection isn't instant, so the API is asynchronous. When you create a form you get back 202 Accepted with a status of processing:

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

Detection then runs in the background. You poll GET /forms/{id} until the status is ready (or failed) — see Tracking jobs.

Two ways to fill

Once a form is ready, fill it whichever way fits your data:

  • From structured data you already have — map your values onto the contract's fields directly. See Fill from your data.
  • From documents — hand Emboss supporting files and let it infer the values. See Fill from context docs.

Both paths work off the same contract, so it's worth a look at the contract shape before you fill.