Field detection

---

title: Field detection

description: How Atlas finds signature fields on PDF and DOCX uploads, what fields_status means, and how to fix wrong placements before send.

date: 2026-06-12

updated: 2026-06-12

---

Ops uploaded a vendor MSA at 4pm. By 4:02 the review page showed twelve fields, but two signature lines landed on paragraph text instead of the signature block. Your job is not to drag boxes for an hour. You need to know what detection did, fix the two mistakes, and send before the counterparty leaves for the day.

Atlas runs automated field detection on every PDF or DOCX upload. Results appear on the review page before send. You confirm or adjust, then dispatch.

Share: AI proposes fields. You confirm in review. Then send.

What happens after upload

When you call POST /api/envelope, Atlas starts async field detection on the stored PDF bytes. DOCX uploads convert to PDF at create time, then follow the same path.

Rough stages:

Cache lookup: same document hash skips repeat work
Page dimensions: local PDF parse for coordinate normalization
Field detection: finds signature lines, initials, dates, text fields, checkboxes
Prose filter: drops labels that look like contract sentences, not form labels
Party grouping: assigns fields to detected parties with party_index
Cache write: stores results for future uploads of the same file

If detection finds zero fields, status becomes recovered_empty and you place fields manually on review.

fields_status states

Poll GET /api/envelope/{id} or watch the review progress bar:

Status	Meaning
`pending`	Detection running. Send returns 409.
`ready`	Fields detected. Safe to send after review.
`failed`	Error. See error banner on review.
`recovered_empty`	Zero fields found. Manual placement fallback.

Never send while pending. Your backend should wait for ready, failed, or recovered_empty.

Detected parties

Party grouping produces detected_parties[] with display names and optional role hints. Each field gets party_index pointing into that list.

When you pass parties[] at create, Atlas matches your signers to detected parties by role or name string. Unmatched parties stay available for witness roles you add manually.

Manual corrections on review

On review you can drag fields, add new ones, rebind party assignment, and prefill text. Saves go to PATCH /api/envelope/{id}/fields with fields_version for optimistic concurrency.

Send bundles fields, parties, and version in one POST /api/envelope/{id}/send from the review UI. Do not PATCH fields separately right before Send from review. That avoids version drift if send fails.

Re-detection

POST /api/envelope/{id}/redetect queues a fresh run. Useful after replacing the underlying PDF.

On failure, Atlas writes an error message in envelope metadata and leaves fields_status as failed or pending. It does not silently flip to ready.

API create example

curl -X POST https://atlaswork.ai/api/envelope \
 -H "Authorization: Bearer $ATLAS_API_KEY" \
 -F "file=@nda.pdf"

Response may include detected_fields on fast paths. Always confirm on review_url.

MCP note

MCP send_contract_for_review triggers the same detection. The agent should tell the operator to open review_url and wait for fields before send. See MCP electronic signatures.

When to re-run detection

Replace the PDF after a material edit? Call redetect instead of guessing field coords in your CRM.

Zero fields on a scanned fax? Expect recovered_empty. Drag boxes on review once, then save a template if the layout repeats.

Production checklist

Poll fields_status before send. Sending while detection is pending returns 409.

If legal rejects auto-placement on a document type, run one manual review cycle, then save as a template for repeat sends.

Log envelope_id and detection status in your job runner so support can trace stuck envelopes.

Credits and billing

Detection and draft uploads are free. You pay one credit when email dispatches at send time. Re-detection on the same envelope does not consume a send credit.

Voiding a pending envelope with zero completed signers refunds one credit if you already sent by mistake.

Compare to manual placement only

Some teams skip detection and place every field by hand. That works for one-page NDAs but does not scale when intake generates fifty-page MSAs weekly.

Detection plus human review gives you speed without trusting automation blindly on first use of a template family.

Wire e-signature API create first, then poll fields_status in your worker. Pair with sequential signing when intake matters need ordered counsel review after client sign.

FAQ

Does detection work on DOCX?

Yes. DOCX converts to PDF at create. Both paths share the same detection flow.

Can I skip review?

Templates and trusted shapes can auto-send once legal approves. Ad-hoc uploads default to review-first.

What if detection fails?

Place fields manually on review or re-upload a cleaner PDF.

Where is the REST map?

e-signature API and sequential signing.

Open one real contract on review before you wire auto-send. Two minutes of human eyes beats a mis-signed page in a counterparty inbox.