> ## Documentation Index
> Fetch the complete documentation index at: https://docs.atlaswork.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Prefill

> Fill values in ahead of signing, on a single field or by template key.

Prefill is a value the sender supplies before a signer ever opens the document.
The signer sees the field already filled and cannot change it, so prefill is for
the terms you already know: a company name, an effective date, an order number.

Prefill works the same way on every surface. The dashboard writes it, the REST
API accepts it on envelope create and on template sends, and MCP agents pass it
as `prefill_map`.

## Prefill on a single field

Text and date fields accept a static `prefillValue`. In the review editor, select
a field and use the **Prefill value** input ("Optional value filled in ahead of
signing"). Through the API, set it on the field when you create the envelope:

```json theme={null}
{
  "participantIndex": 0,
  "type": "text",
  "page": 1,
  "x": 0.12,
  "y": 0.44,
  "width": 0.3,
  "height": 0.04,
  "label": "Company name",
  "required": true,
  "prefillValue": "Acme Robotics"
}
```

Two rules apply everywhere:

* **Checkbox fields ignore prefill.** A checkbox always starts unchecked and
  stays under the signer's control, so consent is never pre-granted on their
  behalf.
* **Prefill and Fill automatically are mutually exclusive.** A field either
  carries a static value or derives one, never both. Sending both on one field
  returns `422` with `validation_error`.

### Prefill versus Fill automatically

The field inspector's **Fill automatically** dropdown is a different feature.
Prefill is a fixed string the sender types now. An automatic field derives its
value on the server at the moment the signer signs (the signing date, the
signer's name, email, company, or title, or the sender's workspace name), and
that derivation is recorded in the envelope's audit trail as machine-filled.

Setting one clears the other in the editor: type a prefill value and the dropdown
is disabled, pick an automatic source and the prefill input disappears.

## Template prefill keys

Saving a template freezes its layout, so the fields need stable names that
survive every future send. When the template is created, Atlas assigns a
snake\_case **prefill key** to each field that can carry a value:

| Field                             | Gets a key?                      |
| --------------------------------- | -------------------------------- |
| Text or date, no automatic source | Yes                              |
| Bound to an automatic source      | No, the value derives at signing |
| Signature, initials, or checkbox  | No                               |

Keys come from the field label, lowercased and slugified: "Company name" becomes
`company_name`. An unlabeled field falls back to its type (`text`, `date`). If two
fields would collide, the second is prefixed with its role name
(`buyer_company_name`), then suffixed numerically if that still collides.

### Reading the keys

`GET /api/v1/templates/{id}` returns the template graph plus a self-describing
contract that lists every key with the role it belongs to and its saved default:

```json theme={null}
{
  "contract": {
    "prefillKeys": [
      {
        "key": "company_name",
        "fieldId": "6f0f...",
        "roleName": "Buyer",
        "label": "Company name",
        "type": "text",
        "defaultValue": "Acme Robotics"
      },
      {
        "key": "effective_date",
        "fieldId": "9c31...",
        "roleName": "Buyer",
        "label": "Effective date",
        "type": "date",
        "defaultValue": null
      }
    ],
    "exampleCreate": {
      "recipients": { "Buyer": { "name": "Buyer", "email": "buyer@example.com" } },
      "prefill": { "company_name": "Acme Robotics" },
      "autoSend": true
    }
  }
}
```

### Passing values at send

`POST /api/v1/templates/{id}/envelopes` takes a flat `prefill` map alongside the
recipients. Each entry overrides the saved default for that field; keys you omit
keep whatever the template stored.

```bash theme={null}
curl -X POST https://api-atlaswork.vercel.app/api/v1/templates/$TEMPLATE_ID/envelopes \
  -H "Authorization: Bearer $ATLAS_API_KEY" \
  -H "Idempotency-Key: 8f1c2b9a-..." \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": {
      "Buyer": { "name": "Ada Lovelace", "email": "ada@example.com" }
    },
    "prefill": {
      "company_name": "Lovelace Analytical",
      "effective_date": "2026-07-14"
    }
  }'
```

<Tip>
  A field's id works as a prefill key too, so a caller holding the template graph can address a
  field directly. Prefer the stable key: it reads clearly in your code and it is what the contract
  payload and the MCP tools advertise.
</Tip>

Template sends default to auto-send, because the layout was already reviewed when
the template was saved. Pass `"autoSend": false` for a review-first draft, which
returns a `reviewUrl` so a human can check the filled values before anything is
emailed.

### When a key doesn't match

An unrecognized key never fails the send. Atlas creates the envelope and reports
the keys it could not place in `prefillUnmatched`:

```json theme={null}
{
  "envelope": { "...": "..." },
  "reviewUrl": "https://...",
  "prefillUnmatched": ["compnay_name"]
}
```

Treat a non-empty `prefillUnmatched` as a bug in the calling code: the value was
dropped and the field went out blank. Re-read the template's `prefillKeys` and
correct the key.

One case does fail: targeting a field bound to an automatic source returns `422`
with `validation_error`, because that field's value is derived at signing and
cannot be overridden by the sender.

## What signers see

A prefilled field renders read-only, styled as already filled, and labeled
"Filled by the sender" on hover and to screen readers. It counts as already
complete in the signer's progress meter, so a required field carrying a prefill
never blocks submission.

At completion the prefilled value is stored on the field exactly like a typed
one, so it is stamped into the signed PDF and returned by structured extraction.

<Note>
  An unusable prefill is ignored rather than locking the field. A stored value on a checkbox, for
  example, leaves the box unchecked and signer-editable, so a field can never be simultaneously
  locked and failing validation.
</Note>

## From the dashboard and from agents

* **Dashboard.** Open a template and expand **Prefill fields** to see every
  fillable field, labeled with the role it belongs to and showing its saved
  default. Values entered there apply to that one send. Fields with an automatic
  source are listed as derived and cannot be edited.
* **MCP.** `get_template` returns `optional_prefill_keys` and an
  `example_create.prefill_map` you can copy;
  [`send_contract_from_template`](/mcp/tools) accepts `prefill_map` with the same
  keys and the same unmatched-key behavior.