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

# Automatic Disposition Guide

> How to configure and review beta automatic disposition predictions for potential screening matches.

export const StorybookFrame = ({storyId, title, version = "20260419-1", height, zoom = 0.7, preferLocalPreview = false}) => {
  const HOSTED_STORYBOOK_BASE_URL = "https://minerva-storybook.s3.ca-central-1.amazonaws.com/iframe.html";
  const isLocalDocsPreview = typeof window !== "undefined" && ["localhost", "127.0.0.1"].includes(window.location.hostname);
  const storybookBaseUrl = preferLocalPreview && isLocalDocsPreview ? "http://localhost:6006/iframe.html" : HOSTED_STORYBOOK_BASE_URL;
  const params = new URLSearchParams({
    id: storyId,
    viewMode: "story",
    singleStory: "true",
    shortcuts: "false",
    toolbar: "0",
    nav: "0",
    panel: "0"
  });
  params.set("v", version);
  const src = `${storybookBaseUrl}?${params.toString()}`;
  const unscaledHeight = `${Math.ceil(height / zoom)}px`;
  const unscaledWidth = `${100 / zoom}%`;
  return <div style={{
    width: "100%"
  }}>
      <div style={{
    height: `${height}px`,
    overflow: "hidden",
    border: "1px solid #e2e8f0",
    borderRadius: "12px",
    backgroundColor: "#ffffff",
    display: "flex",
    justifyContent: "center",
    alignItems: "flex-start"
  }}>
        <iframe src={src} title={title} loading="lazy" style={{
    width: unscaledWidth,
    height: unscaledHeight,
    transform: `scale(${zoom})`,
    border: "0",
    display: "block",
    transformOrigin: "top center",
    flexShrink: 0
  }} allowFullScreen></iframe>
      </div>
    </div>;
};

Automatic disposition helps Minerva classify high-confidence potential screening matches as true matches or false matches after screening has returned a potential match. It is designed to reduce repetitive analyst review while keeping the decision logic visible in the potential match view.

<Warning>
  <strong>Beta feature:</strong> Automatic disposition must be enabled by
  Minerva before your organization can use it. Contact your Minerva
  representative or [support@gominerva.com](mailto:support@gominerva.com) to request access for Calibration and
  Live workspaces.
</Warning>

**Access:** Requires the <strong>Admin</strong> or <strong>Owner</strong> role. In the sidebar, go to <strong>Administration</strong> > <strong>Configuration</strong>, then open <strong>Automatic Disposition</strong> under <strong>Post Processing Behaviours</strong>.

Use this guide when you need to:

* enable automatic disposition for onboarding, monitoring, or Direct API search workflows
* choose between Hint Mode and Full Auto Mode
* interpret true match, false match, and undetermined predictions
* tune confidence thresholds before analysts rely on the output
* test safely in a Calibration workspace before applying settings in Live
* review automatic disposition evidence during match QA and audit

<Info>
  Automatic disposition is workspace-scoped. Start in a Calibration workspace,
  collect examples, and only copy the approved settings into Live after the
  review criteria are documented.
</Info>

## How Automatic Disposition Works

Automatic disposition runs after Minerva has produced a potential match. It does not replace screening or match scoring. Instead, it evaluates the potential match, assigns a prediction, and returns a rationale that analysts can inspect.

For each supported workflow, Minerva can return:

| Prediction                          | Meaning                                                                                                                 | Analyst action                                                                                                      |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| <strong>False match</strong>        | The model found enough evidence that the potential match is likely not the screened subject.                            | Review the rationale and sampled evidence. In Full Auto Mode, this can close the match as a false match.            |
| <strong>True match</strong>         | The model found enough evidence that the potential match is likely the screened subject.                                | Review the rationale and confirm policy handling. In Full Auto Mode, this can apply a true match disposition.       |
| <strong>Undetermined</strong>       | The model could not confidently classify the potential match above the configured threshold.                            | Keep normal manual review. Treat the output as context only, not a disposition.                                     |
| <strong>Could not complete</strong> | The model did not return a usable result, commonly because analysis failed, timed out, or lacked enough usable context. | Use normal manual review and investigate only if failures are frequent or concentrated in a specific workflow/feed. |

Automatic disposition output is visible on the potential match, so reviewers can see whether Minerva only provided a hint or actually applied a disposition.

## Configure The Feature

Open <strong>Automatic Disposition</strong> from tenant configuration. Select the workspace you want to configure before changing any settings.

<StorybookFrame storyId="pages-tenant-config-automatic-disposition--default" title="Automatic Disposition Configuration Page" height={980} version="20260609-1" />

The page includes global enablement, workflow enablement, mode selection, thresholds, and optional prompt guidance.

### Global Enablement

Turn on <strong>Enable automatic disposition</strong> to let Minerva run this post-processing step for the selected workspace.

When the global toggle is off:

* no automatic disposition predictions are generated for that workspace
* outcome settings and thresholds are preserved but inactive
* analysts continue using the standard potential match review flow

### Workflow Enablement

Automatic disposition can be enabled independently for:

| Workflow                            | What it covers                                                                                                                      |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| <strong>Onboarding</strong>         | Potential matches created during initial customer or profile onboarding.                                                            |
| <strong>Ongoing monitoring</strong> | Potential matches created by recurring monitoring checks for existing profiles.                                                     |
| <strong>Direct API</strong>         | Potential matches returned by searches your integrations submit directly with an API key, such as `search-sync` and batch searches. |

Enable one workflow at a time during calibration. Each channel can have different review patterns, data freshness, and analyst tolerance for automation.

### Direct API Channel

The Direct API channel applies the same modes, outcomes, and confidence thresholds to searches submitted directly through the Minerva API. When it is enabled for a workspace:

* Screened potential matches returned by `POST /v1/search-sync`, `GET /v1/search-sync`, and batch search results carry an `automatic_disposition` or `disposition_hint` annotation in the API response.
* Full Auto Mode sets the match `review_status` before the synchronous response or batch row completes. Hint Mode returns an advisory annotation, leaves the match `unresolved`, and lets the integration interpret the prediction in real time.
* Computing dispositions adds a few seconds per screened entity to `search-sync` responses and batch row completion.
* An integration can opt a single request out with the `X-Minerva-Automatic-Disposition: skip` header. The header is inert unless the Direct API channel is enabled for the workspace of the Application whose API key is used.

See the [Automatic Disposition Guide in the API Reference](/api-reference/automatic-disposition-guide) for the response field reference, reading order for integrations, examples, and the opt-out header.

### Privacy Mode

Privacy mode controls how much personally identifiable information Minerva includes in the model context.

| Mode                        | Behavior                                                                 | When to use it                                                                                        |
| --------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
| <strong>Default</strong>    | Sends the standard match context needed for the prediction.              | Use when your organization has approved normal model processing for screening review support.         |
| <strong>Anonymized</strong> | Reduces identifying detail while preserving enough structure for review. | Use when calibration can tolerate less direct identity context.                                       |
| <strong>Redacted</strong>   | Applies the strictest reduction of sensitive context.                    | Use only when your privacy posture requires stronger redaction and you have validated output quality. |

More restrictive privacy modes can reduce model context. Review calibration results before deciding that a stricter privacy mode is appropriate for Live.

### Custom Prompt Guidance

Use the custom prompt field for organization-specific review criteria that analysts already apply, such as jurisdictional policy, source hierarchy, or evidence expectations.

Good prompt guidance is:

* short enough to be consistently applied
* written as policy criteria, not one-off instructions for a single customer
* aligned with your standard operating procedures
* tested against known true match and false match examples

Avoid using custom prompt guidance to override thresholds for a single case. If a case needs different treatment, handle it through manual review.

## Choose Hint Mode Or Full Auto Mode

Each outcome can use either Hint Mode or Full Auto Mode.

| Mode                            | Behavior                                                                                        | Recommended use                                                                                            |
| ------------------------------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| <strong>Hint Mode</strong>      | Shows the prediction, confidence, and rationale on the potential match, but leaves status open. | Use first in Calibration and for outcomes where analysts still need to make the final decision.            |
| <strong>Full Auto Mode</strong> | Applies the configured disposition when confidence meets the threshold.                         | Use only after calibration shows stable precision for the workflow, feed mix, and outcome being automated. |

You can configure false match and true match outcomes separately. For example, an organization might start with false matches in Hint Mode, later move high-confidence false matches to Full Auto Mode, and keep true matches in Hint Mode for manual review.

<Warning>
  Full Auto Mode changes match status without analyst action when the threshold
  is met. Use it only after validating examples in Calibration, documenting the
  decision criteria, and confirming that downstream QA and audit processes can
  review the model rationale.
</Warning>

## Tune Confidence Thresholds

Each configured outcome has a confidence threshold from <strong>0.00</strong> to <strong>1.00</strong>. The threshold controls how confident Minerva must be before that outcome is shown or applied.

* Higher thresholds are stricter. They reduce the number of hints or automatic dispositions but should improve precision.
* Lower thresholds are broader. They can cover more matches but require more QA because weaker predictions are included.
* False match and true match thresholds should be calibrated independently.
* Undetermined predictions are expected when neither enabled outcome reaches its threshold.

Start with conservative thresholds and review enough examples to understand the tradeoff between review volume and decision quality. If automatic false matches look reliable but automatic true matches need more context, tune those outcomes separately.

## Review Output In The Potential Match View

Automatic disposition appears in the potential match view so analysts can inspect the model output beside the underlying match evidence.

<StorybookFrame storyId="pages-screening-potential-match-view--applied-automatic-disposition" title="Potential Match With Applied Automatic Disposition" height={720} version="20260609-1" />

The component shows:

* whether the output was <strong>Applied</strong> or shown as a <strong>Hint</strong>
* the predicted disposition
* the confidence score
* the rationale behind the prediction
* any failure or timeout state when the model could not complete

### Applied Results

An <strong>Applied</strong> label means Minerva used Full Auto Mode and the prediction met the configured threshold.

<StorybookFrame storyId="components-screening-potential-match-automatic-disposition--applied-false-match" title="Applied False Match Prediction" height={280} version="20260609-1" />

For applied false matches, review QA samples to confirm that the rationale matches your analysts' false-positive reasoning. Look for clear differences in identity, dates, locations, occupations, source records, or other evidence that supports non-match treatment.

<StorybookFrame storyId="components-screening-potential-match-automatic-disposition--applied-true-match" title="Applied True Match Prediction" height={280} version="20260609-1" />

For applied true matches, confirm that your policy allows model-applied true match decisions. Some programs prefer true matches to stay in Hint Mode even after false matches move to Full Auto Mode.

### Hints

A <strong>Hint</strong> label means Minerva did not change the match status. The prediction is shown as review context.

<StorybookFrame storyId="components-screening-potential-match-automatic-disposition--disposition-hint" title="False Match Disposition Hint" height={280} version="20260609-1" />

Use hints to build calibration evidence. Analysts should compare the hint with their own disposition and capture patterns where the model is helpful or wrong.

### Undetermined Predictions

Undetermined means Minerva did not find enough confidence for a configured outcome.

<StorybookFrame storyId="components-screening-potential-match-automatic-disposition--undetermined-hint" title="Undetermined Disposition Hint" height={280} version="20260609-1" />

Treat undetermined predictions as a normal result, especially during early calibration. They often indicate borderline matches, weak source evidence, or incomplete subject information. Do not lower thresholds solely to eliminate undetermined results unless QA confirms that the broader predictions remain reliable.

## Calibration Workspace Workflow

Use a Calibration workspace to test settings against real review examples without changing Live analyst outcomes.

1. Ask Minerva to enable the beta for the Calibration workspace.
2. Open <strong>Administration</strong> > <strong>Configuration</strong> > <strong>Automatic Disposition</strong>.
3. Select the Calibration workspace.
4. Enable automatic disposition globally.
5. Enable one workflow, usually onboarding first.
6. Keep false match and true match outcomes in <strong>Hint Mode</strong>.
7. Start with conservative thresholds.
8. Save the settings with a change description that explains the calibration goal.
9. Review potential matches where hints appear.
10. Compare each hint to analyst disposition and note disagreement patterns.
11. Adjust thresholds or prompt guidance in small increments.
12. Repeat until the precision, coverage, and undetermined rate are acceptable.

Track at least:

* workflow and feed mix
* sample size reviewed
* number of false match, true match, and undetermined predictions
* agreement rate with analyst decisions
* serious disagreement examples
* threshold and prompt versions tested
* recommended Live posture

## Promote Settings To Live

There is no separate promotion button for Automatic Disposition. After Calibration is approved, switch to the Live workspace and apply the approved settings there.

Use this controlled rollout sequence:

1. Export or record the approved Calibration settings, thresholds, privacy mode, and prompt guidance.
2. Switch the workspace selector to <strong>Live</strong>.
3. Recreate the approved settings exactly.
4. Keep outcomes in Hint Mode for the first Live observation window unless your governance process has already approved Full Auto Mode.
5. Save with a change description that references the Calibration review.
6. Monitor Live output volume, disagreement examples, and analyst feedback.
7. Move an outcome to Full Auto Mode only when Live hints match the approved Calibration behavior.
8. Revisit thresholds after source mix, workflow, or policy changes.

<Tip>
  Promote one outcome at a time. Many teams start with false match hints, then
  high-confidence false match automation, and only later consider true match
  automation.
</Tip>

## QA And Audit Checklist

Before enabling Full Auto Mode in Live, confirm that your team can answer:

* Which workspace and workflow are affected?
* Which outcome is automated: false match, true match, or both?
* What thresholds are active?
* What calibration sample supports the threshold?
* What custom prompt guidance was used?
* Which user saved the change and why?
* How often will applied decisions be sampled for QA?
* Who can roll back the setting if output quality changes?

During ongoing QA, reviewers should inspect:

* model rationale for applied decisions
* match evidence and field-level identity comparison
* whether the same source or feed is overrepresented in disagreements
* whether policy changes require threshold or prompt updates
* whether analysts are relying on hints appropriately

## Related Guides

* [Screening Guide](/screening-guide)
* [Match Scoring Guide](/match-scoring-guide)
* [Role-Aware Adverse Media Guide](/role-aware-adverse-media-guide)
* [Workspaces Guide](/workspaces-guide)
* [Exports Guide](/exports-guide)