Confidence and HITL

Per-field confidence scores, human-review thresholds, and routing low-confidence results.

Folio attaches a confidence score to every extracted field and compares it against a configurable threshold to decide whether a document needs human review. This guide explains the signals available and how to build a human-in-the-loop (HITL) workflow around them.

Per-field confidence

Every field in the extract object carries two signals:

Field	Type	Description
confidence	float 0–1	Model’s confidence that the extracted value is correct. 1.0 = certain, 0.0 = no confidence.
found	boolean	true if the field was located in the document; false if it was absent or not detectable.

{
  "extract": {
    "patient_name": {
      "value": "Jane Doe",
      "confidence": 0.99,
      "found": true,
      "page": 1,
      "bbox": {"x": 0.05, "y": 0.12, "width": 0.15, "height": 0.02},
      "block_ids": ["p1-b3"]
    },
    "test_date": {
      "value": null,
      "confidence": 0.0,
      "found": false,
      "page": null,
      "bbox": null,
      "block_ids": []
    }
  }
}

When found is false, value is null and confidence is 0.0.

Human-review threshold

The human_review_threshold parameter (0–1) sets the minimum per-field confidence required to pass without flagging for review. Any field whose confidence falls below this threshold causes the document’s review_status to be set to needs_review.

• Default server-side threshold: 0.85
• Per-request override: pass human_review_threshold as a form field in POST /v1/documents.

curl -X POST https://api.glialhealth.com/v1/documents \
  -H "Authorization: Bearer sk_test_..." \
  -F file=@claim.pdf \
  -F document_type=insurance_claim \
  -F human_review_threshold=0.90

A threshold of 1.0 forces every document into needs_review. A threshold of 0.0 disables per-field confidence gating (documents can still be flagged for other reasons).

review_status

Value	Meaning
auto	All fields met the confidence threshold; no human review required.
needs_review	One or more fields fell below the threshold, or a validation flag was raised. A human should verify before acting on the result.

review_status is set once when the document reaches a terminal state and does not change.

Flags

The flags array lists all reasons that contributed to needs_review. Flags are strings:

Flag	Trigger
low_confidence_field:<name>	The named field’s confidence is below human_review_threshold.
low_confidence_classification	The document-type classifier’s confidence (document_type_confidence) is low.
missing_field:<key>	A field marked required in the extraction schema was not found.
invalid_field:<key>	A field’s extracted value failed the pattern or type check in the schema.

Example result with flags:

{
  "review_status": "needs_review",
  "flags": [
    "low_confidence_field:test_date",
    "missing_field:lab_accession_number"
  ],
  "document_type_confidence": 0.95
}

Routing needs_review documents

A typical HITL workflow:

1. Receive the result

   Via webhook or poll, check review_status.

   if result["review_status"] == "needs_review":
       enqueue_for_human_review(result)
   else:
       process_automatically(result)
   
2. Surface flagged fields to the reviewer

   Parse the flags array to highlight only the fields that need attention, rather than asking the reviewer to check everything.

   flagged_fields = [
       f.split(":")[1]
       for f in result["flags"]
       if f.startswith("low_confidence_field:") or f.startswith("missing_field:")
   ]
   # Show reviewer: result["extract"][field] for each flagged_fields entry
   

   Use bbox coordinates to draw overlays on the document image so the reviewer can locate the field at a glance.

3. Record the correction

   Your application stores the human-corrected values. Folio does not accept corrections back via the API — the correction lives in your system of record.

document_type_confidence

In addition to per-field confidence, the result includes a top-level document_type_confidence (0–1) indicating how confident the classifier was about the detected document type. When this is low, the low_confidence_classification flag is raised, and review_status becomes needs_review even if all field confidences are high.