GuidesAPIMCP

Field detection

When you upload a PDF or DOCX, Atlas runs an automated pipeline to find signature lines, initial blocks, dates, text fields, and checkboxes. Results appear on the review page before send.

Pipeline overview

  1. Cache lookup — prior runs for the same document hash skip network calls
  2. Page dimensions — local PDF parse for coordinate normalization
  3. Extend Edit Schema — per-field detection (no party clustering in this step)
  4. Mapper — converts vendor schema to Atlas field types with bounding boxes
  5. Prose filter — drops text fields whose labels look like contract prose, not form labels
  6. Claude clustering — groups fields into detected parties and assigns party_index
  7. Cache write — stores field list for future uploads of the same file

If Extend returns zero fields, status becomes recovered_empty and you place fields manually on review.

fields_status states

StatusMeaning
pendingDetection running. Send returns 409.
readyFields detected. Safe to send after review.
failedPipeline error. See metadata.detection_error on review.
recovered_emptyZero fields found. Manual placement fallback.

Never send while pending. Poll GET /api/envelope/{id} or watch the review page progress bar.

Detected parties

Clustering 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 or CC-style roles you add manually.

Manual corrections

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 review UI. Do not PATCH fields separately right before Send from review (avoids version drift on failure).

Re-detection

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

Detection errors

On failure, Atlas writes metadata.detection_error: { message, stage, occurred_at } and leaves fields_status as failed or pending. It does not silently flip to ready.

Background stage updates land in metadata.detection_stage and metadata.detection_progress for the review UI.

Formats

Detection runs on PDF bytes. DOCX uploads convert to PDF at create time. Both paths share the same pipeline.

API create with detection

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 pipeline. The agent should tell the operator to open review_url and wait for fields before send.

Related guides