> ## 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 consume Automatic Disposition outputs - review_status, automatic_disposition, and disposition_hint - in Direct API screening integrations.

Minerva's [Automatic Disposition](/automatic-disposition-guide) can now run on
Direct API searches as a third channel alongside Onboarding and Ongoing
monitoring. When the Direct API channel is enabled for your workspace, Minerva
analyzes each screened potential match before the search response or batch row
completes and annotates the match with its prediction:

* In **Full Auto Mode**, a prediction that meets the configured confidence
  threshold sets the match `review_status` and is returned in
  `automatic_disposition`.
* In **Hint Mode**, the prediction is advisory only: it is returned in
  `disposition_hint`, `review_status` stays `unresolved`, and your integration
  decides in real time how to act on it.

This guide covers how an integration should read and act on those outputs.

<Warning>
  <strong>Availability:</strong> Automatic Disposition is enabled per workspace
  by your administrators once the feature is activated for your organization.
  Reach out to the Minerva team - your Minerva representative or
  [support@gominerva.com](mailto:support@gominerva.com) - to get it enabled.
</Warning>

## Before You Start

First review the [Screening Integration
Guide](/api-reference/screening-integration-guide) for the base interpretation
of screening response fields: risk flags in `checklist.screen`, identity match
strength in `score`, and the supporting evidence trail. Automatic Disposition
layers an adjudication signal on top of that model - it does not replace the
risk finding, the match score, or the evidence an analyst would review.

For the concepts behind the feature - modes, outcome policies, confidence
thresholds, privacy modes, calibration workflow, and QA guidance - see the
[Automatic Disposition product guide](/automatic-disposition-guide). Those
settings are managed by workspace administrators and determine everything your
integration receives.

## Where The Fields Appear

The annotations are returned on the per-match `Profile` objects of the Direct
API search surfaces:

| Surface                   | Endpoint                                                                                                                        | Match objects           |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| Synchronous single search | [`POST /v1/search-sync`](https://docs.gominerva.com/api-reference/search/single-search-synchronous-api)                         | `results[i]`            |
| Legacy synchronous search | [`GET /v1/search-sync`](https://docs.gominerva.com/api-reference/legacy/single-search-synchronous-api-get)                      | `results[i]`            |
| Batch search results      | `POST /v1/searchStatus` or [`GET /v1/search/{jobid}`](https://docs.gominerva.com/api-reference/search/batch-search-results-api) | `results[n].results[i]` |

A match carries the fields only when all of the following are true:

* The workspace that owns the API application has Automatic Disposition
  enabled with the **Direct API** channel turned on.
* The potential match is screened - it carries at least one risk flag
  (Sanctions, PEP, News, Criminal, Legal, and so on) in `checklist.screen`.
* The request was not opted out with the
  [`X-Minerva-Automatic-Disposition: skip`](#opt-a-request-out) header.

Clean matches (no flagged feed) and workspaces without the feature enabled
never carry these fields. The fields are additive, so integrations that ignore
unknown response fields are unaffected.

<Note>
  <strong>Latency:</strong> dispositions are computed before the synchronous
  response returns and before each batch row completes. Expect enabling the
  Direct API channel to add a few seconds per screened entity to `search-sync`
  responses and to batch row completion.
</Note>

## Reading Order For A Match

Read the disposition output in this order for each screened potential match:

1. **Check `review_status` first.** If it is `true_positive` or
   `false_positive` and `automatic_disposition` is present, Minerva already
   adjudicated the match according to your workspace policy (Full Auto Mode).
   Apply your corresponding case handling - for example, close auto-resolved
   false positives and escalate auto-confirmed true positives - and retain the
   annotation with the case record.
2. **Then check `disposition_hint`.** The match is still `unresolved`; the
   hint is an advisory signal your integration can use to route, prioritize,
   or pre-populate the review.
3. **If neither annotation is present**, treat the match as a normal
   unreviewed potential match. Absence of an annotation is not evidence of a
   clean result: the match may be clean (no flagged feed), the workspace or
   channel may be disabled, the request may have been opted out, or the
   analysis may not have run for that match.

| `review_status`                    | Annotation present      | Meaning                                               | Suggested handling                                            |
| ---------------------------------- | ----------------------- | ----------------------------------------------------- | ------------------------------------------------------------- |
| `true_positive` / `false_positive` | `automatic_disposition` | Minerva applied the disposition per workspace policy. | Apply your true/false match case handling; log the rationale. |
| `unresolved`                       | `disposition_hint`      | Advisory prediction; no status change.                | Route to human review with the hint as context.               |
| `unresolved`                       | None                    | Not analyzed, opted out, failed, or clean match.      | Normal manual review flow.                                    |

## How Annotations Relate To `review_status`

`review_status` on a potential match starts as `unresolved`. Automatic
Disposition changes it **only** in Full Auto Mode:

| Scenario                                                      | Annotation returned                                        | `review_status`                            |
| ------------------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------ |
| Outcome in Full Auto Mode, confidence meets threshold         | `automatic_disposition`                                    | Set to `true_positive` or `false_positive` |
| Outcome in Hint Mode                                          | `disposition_hint`                                         | Stays `unresolved`                         |
| Analysis completed without meeting a threshold                | `disposition_hint` with `prediction: "undetermined"`       | Stays `unresolved`                         |
| Analysis failed for the match                                 | Annotation with `analysis_status: "failed"` and an `error` | Stays `unresolved`                         |
| Analysis could not run for the match (for example, a timeout) | None                                                       | Stays `unresolved`                         |

Automatic Disposition fails open: a failure never blocks the search, and any
match it could not confidently classify remains in the normal manual review
flow.

## Annotation Fields

`automatic_disposition` and `disposition_hint` share the same shape:

| Field               | Type   | Meaning                                                                                                                            |
| ------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| `prediction`        | string | `true_positive`, `false_positive`, or `undetermined`. `undetermined` appears only on `disposition_hint`.                           |
| `confidence`        | number | Model confidence in the prediction, from `0` to `1`.                                                                               |
| `analysis_status`   | string | `completed` or `failed`. When `failed`, the match is left `unresolved` for normal manual review.                                   |
| `rationale`         | string | Short natural-language explanation of the prediction for analyst review.                                                           |
| `evidence_refs`     | array  | References to the match payload fields and articles the model relied on.                                                           |
| `score_summary`     | object | Per-field score breakdown produced by the disposition analysis.                                                                    |
| `risk_flags`        | array  | Risk signals the analysis surfaced while reviewing the evidence.                                                                   |
| `signature_version` | string | Automatic Disposition prompt/signature version used for the analysis.                                                              |
| `source`            | string | Screening channel that produced the annotation. Always `direct_api` for Direct API searches.                                       |
| `error`             | object | Bounded error metadata (`code`, `message`, `retryable`), present only when the analysis could not complete cleanly for this match. |

## Use Predictions In Automated Workflows

Patterns that work well when layering the outputs into an integration:

* **Route on `review_status` first.** Auto-resolved matches can flow straight
  into your case-closure or escalation logic because the workspace policy has
  already been applied.
* **Apply your own client-side confidence threshold to hints.** Your
  integration can be stricter than the workspace threshold - for example, only
  surface hints with `confidence >= 0.97` in a fast-track queue and send the
  rest to the standard queue.
* **Route unresolved-with-hint matches to human review queues** with
  `prediction`, `confidence`, and `rationale` attached as reviewer context.
  Prioritizing queues by prediction and confidence reduces time spent on
  likely false positives.
* **Log `rationale`, `evidence_refs`, `score_summary`, and
  `signature_version` with the case record.** They are the audit material that
  explains why the model predicted what it did, and they let QA sample
  decisions against specific prompt versions.
* **Treat `undetermined` as normal manual review**, not as a weak positive or
  negative signal.
* **Never treat the absence of an annotation as clearance.** A match without
  annotations still requires your standard review flow.

If your program allows acting on hints automatically, gate the action on your
own documented policy and thresholds: hints do not change Minerva's review
state, so your integration's action becomes the system of record.

## Hint Mode Or Full Auto Mode

Which annotations you receive is a workspace policy decision, made per outcome
(true match and false match separately):

| Mode           | What the integration receives                                                              | Trade-off                                                                                      |
| -------------- | ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- |
| Hint Mode      | `disposition_hint` on screened matches; `review_status` untouched.                         | Integration keeps full control and can calibrate against analyst decisions before automating.  |
| Full Auto Mode | `automatic_disposition` plus an already-applied `review_status` when the threshold is met. | Less review volume, but decisions are applied without analyst action - requires calibrated QA. |

<Tip>
  Calibrate before automating. Start the Direct API channel in Hint Mode,
  compare `disposition_hint` output against your analysts' decisions, and move
  an outcome to Full Auto Mode only after the [calibration
  workflow](/automatic-disposition-guide#calibration-workspace-workflow) shows
  stable precision.
</Tip>

## Example: Hint Mode

The workspace runs the true match outcome in Hint Mode. The prediction is
returned in `disposition_hint` and `review_status` stays `unresolved` - the
annotation is advisory context for your integration and analysts. The values
below are illustrative and abbreviated.

```json theme={null}
{
  "score": 0.97,
  "name": {
    "value": "John Example",
    "match_score": 0.97,
    "criteria_match_level": "close"
  },
  "checklist": {
    "screen": {
      "Sanctions": true,
      "PEP": false,
      "News": false
    }
  },
  "review_status": "unresolved",
  "disposition_hint": {
    "prediction": "true_positive",
    "confidence": 0.99,
    "analysis_status": "completed",
    "source": "direct_api",
    "rationale": "The searched subject matches the potential match on name and country context, and no discovered identity attribute contradicts the match."
  }
}
```

## Example: Full Auto Mode

The workspace runs the false match outcome in Full Auto Mode and the
prediction met the configured threshold. Minerva sets `review_status` before
the response returns, and the applied prediction is returned in
`automatic_disposition`.

```json theme={null}
{
  "score": 0.88,
  "name": {
    "value": "John Example",
    "match_score": 0.92,
    "criteria_match_level": "close"
  },
  "checklist": {
    "screen": {
      "Sanctions": false,
      "PEP": true,
      "News": false
    }
  },
  "review_status": "false_positive",
  "automatic_disposition": {
    "prediction": "false_positive",
    "confidence": 0.95,
    "analysis_status": "completed",
    "source": "direct_api",
    "rationale": "The searched subject's occupation and country conflict with the listed person, and the date of birth reported by the triggering source does not align with the submitted subject."
  }
}
```

## Opt A Request Out

Send the `X-Minerva-Automatic-Disposition: skip` header to suppress Automatic
Disposition for a single search, even when the workspace has the Direct API
channel enabled. Every returned match is left `unresolved` with no annotation.
For a batch submission, the header opts out every row in that job.

```bash theme={null}
curl -X POST https://api.gominerva.com/v1/search-sync \
  -H "x-api-key: YOUR_API_KEY" \
  -H "X-Minerva-Automatic-Disposition: skip" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "individual",
    "name": "John Example",
    "feeds": ["Sanctions", "PEP", "News"]
  }'
```

The header only has an effect when your organization has been opted into
Automatic Disposition and an administrator has enabled it - with the Direct API
channel turned on - in the workspace of the Application whose API key you are
using. Otherwise it is inert: the search behaves as if the feature is off.

The header value is matched case-insensitively; values other than `skip` are
ignored. Searches submitted without the header follow the workspace Automatic
Disposition configuration.

## Related Documentation

* [Automatic Disposition product guide](/automatic-disposition-guide) - modes,
  thresholds, outcome policy, calibration, and QA workflow
* [Screening Integration Guide](/api-reference/screening-integration-guide) -
  mapping the full screening response into a review workflow
* [Single Search Synchronous API](https://docs.gominerva.com/api-reference/search/single-search-synchronous-api)
* [Batch Asynchronous Search API](https://docs.gominerva.com/api-reference/search/batch-asynchronous-search-api)
* [Batch Search Results API](https://docs.gominerva.com/api-reference/search/batch-search-results-api)