Automatic Disposition Guide

Minerva’s Automatic Disposition 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.

Availability: 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 - to get it enabled.

Before You Start

First review the 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. 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`	`results[i]`
Legacy synchronous search	`GET /v1/search-sync`	`results[i]`
Batch search results	`POST /v1/searchStatus` or `GET /v1/search/{jobid}`	`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 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.

Latency: 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.

Reading Order For A Match

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

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

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 shows stable precision.

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.

{
  "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.

{
  "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.

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.

Automatic Disposition product guide - modes, thresholds, outcome policy, calibration, and QA workflow
Screening Integration Guide - mapping the full screening response into a review workflow
Single Search Synchronous API
Batch Asynchronous Search API
Batch Search Results API

​Before You Start

​Where The Fields Appear

​Reading Order For A Match

​How Annotations Relate To review_status

​Annotation Fields

​Use Predictions In Automated Workflows

​Hint Mode Or Full Auto Mode

​Example: Hint Mode

​Example: Full Auto Mode

​Opt A Request Out

​Related Documentation

Before You Start

Where The Fields Appear

Reading Order For A Match

How Annotations Relate To `review_status`

Annotation Fields

Use Predictions In Automated Workflows

Hint Mode Or Full Auto Mode

Example: Hint Mode

Example: Full Auto Mode

Opt A Request Out

Related Documentation