> ## Documentation Index
> Fetch the complete documentation index at: https://docs.glialhealth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.    |

```json theme={null}
{
  "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`.

```bash theme={null}
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:

```json theme={null}
{
  "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:

<Steps>
  <Step title="Receive the result">
    Via webhook or poll, check `review_status`.

    ```python theme={null}
    if result["review_status"] == "needs_review":
        enqueue_for_human_review(result)
    else:
        process_automatically(result)
    ```
  </Step>

  <Step title="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.

    ```python theme={null}
    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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## `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.