Skip to main content
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:
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: 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:

​
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.
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.
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:
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.
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.

​
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 accepts prefill_map with the same keys and the same unmatched-key behavior.