Confidence and HITL

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}
    },
    "test_date": {
      "value": null,
      "confidence": 0.0,
      "found": false,
      "page": null,
      "bbox": null
    }
  }
}

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:

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)

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.

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.

Get started

Guides

API reference

Confidence and HITL

Per-field confidence

Human-review threshold

`review_status`

Flags

Routing `needs_review` documents

`document_type_confidence`

​Per-field confidence

​Human-review threshold

​review_status

​Flags

​Routing needs_review documents

​document_type_confidence

Per-field confidence

Human-review threshold

`review_status`

Flags

Routing `needs_review` documents

`document_type_confidence`