docs
View as Markdown

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.

Adobe LiveCycle (XFA) forms

Some government forms are built with Adobe LiveCycle Designer; Emboss reads their XML template directly instead of running detection, as described in XFA forms. A form whose layout flows or repeats rows is accepted but has nothing to fill: it ends ready with no fields and the warning code xfa_dynamic_form, and its creation is still charged. Open it in Acrobat or Adobe Reader, print it to PDF, and upload that copy instead.