Skip to main content
DocuTrust’s AI field detection runs through a multi-stage pipeline to produce templates that are consistent in field type, position, size, and key naming across documents. This guide explains the architecture, how to interpret the new response fields, and when to trust vs. review the output.
This applies to accounts on pipeline v2. Legacy (v1) responses do not include the pipeline metadata block or the extended preferences fields described below. Rollout is account-by-account; existing API consumers are unaffected by the additions.

​
Why this exists

The legacy detection path was a single LLM call that returned field types and positions as raw coordinates. Three recurring failure modes motivated v2:
  • Wrong sizes — the model occasionally returned w: 0, h: 0 and the backend silently applied a generic default, producing templates where every field was the same size regardless of the actual blank on the page.
  • Inconsistent keys — the same semantic field (e.g. a phone number) could come back as phone, tel, or contact_phone depending on the document, making downstream field mapping brittle.
  • No review loop — a single uncertain extraction was returned verbatim with no self-check, so low-confidence placements reached end signers.
V2 addresses each of these with dedicated stages.

​
Pipeline stages

Each stage is independently testable. The pipeline is deterministic enough across runs (Gemini 3 at default temperature, with strict response schema) to make a test harness against hand-labeled ground truth practical.

​
Response shape

Every smart_setup and smart_create call on a v2 account returns a pipeline metadata block and richer preferences on each field.

​
Top-level pipeline metadata

​
Per-field preferences

On v2, each detected field gets four additional preferences entries:
  • key — Canonical snake_case identifier (max 50 chars, regex ^[a-z][a-z0-9_]{0,49}$). Pulled from DocuTrust’s field library when the label semantically matches a known field; minted from the label otherwise. Same semantic field in the same document always gets the same key, and duplicates across documents are deduped with _2, _3 suffixes.
  • confidence — Float 0–1, self-reported model certainty on BOTH the field type AND its placement. See the calibration table below.
  • anchor_text — The verbatim label text near the field as it appears on the PDF. Useful for building audit trails (“we detected a signature because we saw the label Client Signature:”).
  • anchor_method — How the field’s position was finalized:
    • snapped_to_blank — aligned to an underscore run in the text layer. Highest precision.
    • snapped_to_label — aligned to the preceding label (no underscore run found nearby).
    • llm_only — kept the raw model coordinates (text layer present but no anchor matched).
    • no_text_layer — scanned PDF, no text layer available — expect lower positional accuracy.
    • page_missing — the requested page wasn’t present in the document.

​
Confidence calibration

If any field in a response has confidence < 0.85, or the Normalizer applied corrections, or a field has anchor_method: llm_only, the Critic stage fires a second LLM pass to audit and correct. Look at the top-level critic_ran to see if this happened.

​
Canonical keys

To keep field names stable across documents, the Detector prompt injects DocuTrust’s canonical key library (signatures, common PII fields, consent checkboxes, role-prefixed variants, etc.) and instructs the model to prefer an existing key when the label semantically matches. Examples: For labels with no canonical match, a new snake_case key is minted from the label and enforced through the ^[a-z][a-z0-9_]{0,49}$ regex.

​
Providing context

smart_setup and smart_create accept an optional context object on the v2 pipeline only. It provides advisory document information without changing the detection task or placement rules:
document_hint applies to the whole request; a matching per_document hint takes precedence for that attachment. instructions can provide additional guidance. Hints are advisory: the detector trusts visible PDF content whenever a hint conflicts with the document. expected_fields supplies canonical keys (and optional names/types) for fields that are actually visible. With the default merge_mode: "extend", these fields supplement the account field library and win on key collisions. Use merge_mode: "replace" to use only the supplied list; it requires at least one valid expected field. Expected fields never authorize invented fields: the detector is explicitly instructed not to emit a field that is not visibly present. Legacy v1 silently ignores context, including malformed values. Each run records whether context was supplied (which keys, how many expected fields, the merge mode) in its diagnostic row — correlate via the response’s pipeline.request_id — so detection quality with and without context can be compared per account.

​
Text-layer anchoring

For PDFs with a text layer (most PDFs generated from Word, DocuSign, HelloSign, etc.), the Anchor stage finds the exact pixel-accurate position of the underscore run or labeled blank in the document and replaces the LLM’s coordinates with those. This is the single biggest source of precision improvement in v2. Scanned PDFs without a text layer skip anchoring automatically (anchor_method: no_text_layer) — the LLM output is kept as-is, and expect roughly LLM-quality precision on those fields.

​
What consumers should do

  • New integrations — treat preferences.key as the stable identifier for cross-document field mapping. Do not rely on name (human-readable, may vary) or uuid (random, changes every detection).
  • Existing integrations — no changes required. The new response fields are additive; the shape of fields[i], areas[i], and the top-level response is preserved.
  • Error investigation — when an auto-mapped template looks wrong, send support the pipeline.request_id. It correlates to a diagnostic row with the raw model response, every correction applied, and the anchor method per field.
  • Confidence thresholds — if you auto-accept auto-mapped templates without human review, consider gating on minimum confidence (e.g. only accept templates where all fields have confidence >= 0.85).

​
Compatibility

  • Response fields are additive. No existing property was removed or changed in type.
  • Accounts not yet on v2 continue to receive the legacy response shape (fields[i].preferences = {}, no top-level pipeline block).
  • v1 and v2 share the existing request format, HTTP status codes, and error payload shapes. The optional context request property is v2-only; v1 silently ignores it.