# 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](/docs/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`:

```json
{ "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](/docs/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](/docs/fill-from-data).
- **From documents**: hand Emboss supporting files and let it infer the values.
  See [Fill from context docs](/docs/fill-from-context).

Both paths work off the same contract, so it's worth a look at
[the contract shape](/docs/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](/docs/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.

## See also

- [Turn a flat PDF into a fillable form](https://getemboss.ai/use-cases/flat-pdf-to-fillable)
- [Form field detection](https://getemboss.ai/glossary/form-field-detection)
- [Fill from your data](https://getemboss.ai/docs/fill-from-data)
- [XFA forms](https://getemboss.ai/docs/xfa-forms)
- [Forms](https://getemboss.ai/docs/reference/create-form)