Screening Integration Guide

Use this guide to map Minerva screening responses into an integration, case management system, or analyst review workflow. It focuses on the fields needed to answer four practical questions:

Did Minerva find a Sanctions, PEP, or News/adverse-media indicator?
How closely does the potential match resemble the submitted subject?
Which identity details and sources support or contradict the match?
How can an integration retrieve the same evidence later from profile and search history?

A potential match is a candidate for analyst review. It is not a confirmed identity match, a legal conclusion, or an instruction to accept or reject a customer. Apply your organization’s policies and human-review requirements when determining the final disposition.

The Screening Response Mental Model

Keep risk, identity match strength, and source evidence separate:

Layer	Question	Primary fields
Risk finding	Did a requested screening feed identify a qualifying finding?	`checklist.screen`, `checklist.hits`, `checklist.hits_info[]`
Identity match strength	How closely does this candidate resemble the submitted subject?	`score`, `match_score_info`, field-level `match_score`, field-level `criteria_match_level`
Supporting evidence	Which records, identifiers, relationships, articles, and context explain it?	`source_details[]`, sourced-field `sources[]`, `ID`, `links[]`, `notes[]`, `documents[]`, `websites[]`, `media`

For a synchronous search, every results[i] object is one ranked potential match. For the historical match API, the equivalent object is matches[i]. The same interpretation applies at either path.

Detect Sanctions, PEP, And News

The direct risk indicators are:

Category	Direct flag	Triggering source names	Source-specific identity comparison
Sanctions	`results[i].checklist.screen.Sanctions`	`results[i].checklist.hits.Sanctions`	`checklist.hits_info[]` where `feed == "Sanctions"`
PEP	`results[i].checklist.screen.PEP`	`results[i].checklist.hits.PEP`	`checklist.hits_info[]` where `feed == "PEP"`
News / adverse media	`results[i].checklist.screen.News`	`results[i].checklist.hits.News`	`checklist.hits_info[]` where `feed == "News"`

A true value means Minerva found a qualifying finding for that candidate in that feed. A false value means no qualifying hit was found for that candidate given the requested feeds, submitted identifiers, available source coverage, and configured thresholds. It is not a universal guarantee that the subject has no risk outside the scope of that screen.

Always retain the original search request with the response. It tells a reviewer which feeds and identifiers were actually available to the matching logic and prevents a missing input from being misread as contradictory evidence.

The `checklist` Hierarchy

results[i]
└── checklist
    ├── screen
    │   ├── Sanctions: boolean
    │   ├── PEP: boolean
    │   └── News: boolean
    ├── hits
    │   ├── Sanctions: string[]
    │   ├── PEP: string[]
    │   └── News: string[]
    └── hits_info[]
        ├── source
        ├── feed
        ├── name
        ├── occupation
        ├── organization
        ├── nationality
        ├── date
        └── locations[]

Each hits_info identity attribute generally includes:

Field	Meaning
`value`	Original value reported by the source.
`match_score`	Numeric similarity between the submitted value and the source value.
`criteria_match_level`	Human-readable label: `exact`, `close`, `loose`, or `none`.

An optional hits_info attribute can have match_score: 0.0 when that attribute was not supplied in the original search. For example, if the request did not include a DOB or occupation, zero for that comparison should not automatically be treated as conflicting evidence.

Detailed Sanctions Example

The following abbreviated example is illustrative. It shows the relationship between the overall candidate, the feed flag, the triggering source, and source-reported identity values.

{
  "score": 0.94,
  "match_score_info": {
    "name": {
      "score": 0.96,
      "criteria_match_level": "close",
      "verified": true
    },
    "date": {
      "score": 1.0,
      "criteria_match_level": "exact",
      "verified": true
    },
    "country": {
      "score": 1.0,
      "criteria_match_level": "exact",
      "verified": true
    }
  },
  "name": {
    "value": "Alex Example",
    "match_score": 0.96,
    "criteria_match_level": "close",
    "sources": [
      {
        "value": "ALEKS EXAMPLE",
        "source": "Example Sanctions List",
        "feed": "Sanctions",
        "match_score": 0.96,
        "criteria_match_level": "close"
      }
    ]
  },
  "time_begin": {
    "value": { "year": 1982, "month": 4, "day": 10 },
    "match_score": 1.0,
    "criteria_match_level": "exact"
  },
  "checklist": {
    "screen": {
      "Sanctions": true,
      "PEP": false,
      "News": false
    },
    "hits": {
      "Sanctions": ["Example Sanctions List"]
    },
    "hits_info": [
      {
        "source": "Example Sanctions List",
        "feed": "Sanctions",
        "name": {
          "value": "ALEKS EXAMPLE",
          "match_score": 0.96,
          "criteria_match_level": "close"
        },
        "date": {
          "value": "1982-04-10",
          "match_score": 1.0,
          "criteria_match_level": "exact"
        },
        "nationality": {
          "value": "Example Country",
          "match_score": 1.0,
          "criteria_match_level": "exact"
        },
        "locations": [
          {
            "value": "Example City, Example Country",
            "match_score": 0.9,
            "criteria_match_level": "close"
          }
        ]
      }
    ]
  },
  "ID": {
    "Passport": {
      "value": "EXAMPLE-1234",
      "sources": [
        {
          "value": "EXAMPLE-1234",
          "source": "Example Sanctions List",
          "feed": "Sanctions"
        }
      ]
    }
  },
  "source_details": [
    {
      "name": "Example Sanctions List",
      "source_feed": "Sanctions",
      "flagged_feeds": ["Sanctions"],
      "description": "Illustrative official-list record.",
      "urls": [],
      "inferences": []
    }
  ]
}

A review workflow should read this example in the following order:

checklist.screen.Sanctions confirms that the Sanctions feed flagged.
score says the overall candidate is a strong criteria match.
checklist.hits.Sanctions names the list that triggered the risk finding.
The matching hits_info item shows the original name, date, nationality, and location reported by that list.
ID, source_details, sourced-field sources[], and notes provide corroborating or contradictory evidence for disposition.

Overall Score And Field-Level Closeness

The overall candidate match score is results[i].score. It is normalized from 0.0 to 1.0, with values closer to 1.0 indicating stronger agreement with the submitted search criteria. The score is:

a criteria match score, not a risk-severity score
not a statistical probability that the candidate is the same person
not a measure of how sanctioned, politically exposed, or adverse the subject is
not necessarily a simple average of the visible field scores

For example, score: 0.92 means that the candidate matched the submitted identity criteria strongly. It does not mean “92% sanctioned” or “92% risky.” In a name-only request, a score of 1.0 normally means the candidate name matched the submitted name fully. In a name-and-DOB request, a 1.0 normally means both scored criteria matched fully. When optional evidence is unavailable, workspace matching settings can apply missing-evidence treatment rather than counting absence as a direct contradiction. The field-level summary is results[i].match_score_info.<field>. Common keys include:

name and aliases
date
address, city, state, and country
gender
occupation and organization
email and phone
personalId and registrationId
notes

Each populated field can include score, criteria_match_level, and verified. The verified flag indicates that the field met Minerva’s verification requirements for source reputation and closeness; it should not be treated as a final identity disposition on its own.

Closeness Labels

Label	Score range	Interpretation
`exact`	`0.98` or higher	Effectively exact.
`close`	`0.85` to below `0.98`	Strongly similar, but not exact.
`loose`	`0.75` to below `0.85`	Weaker fuzzy-match evidence.
`none`	Below `0.75`	No meaningful matching evidence from the field.

The closeness label can appear at several levels:

Path	What it compares
`match_score_info.<field>.criteria_match_level`	Summary for one field supplied in the search.
`<profile_field>.criteria_match_level`	Search input compared with the resolved consensus field value.
`<profile_field>.sources[n].criteria_match_level`	Search input compared with one source observation.
`checklist.hits_info[n].<field>.criteria_match_level`	Search input compared with the value reported by the triggering source.

Several agreeing exact or close identifiers generally deserve the most attention. A close name alone can still be a false positive when DOB, location, nationality, or identifiers conflict. Conversely, transliteration, initials, reversed names, punctuation, spelling variations, and partial dates can produce a legitimate match without every field being exact.

Consensus Values And Source Data Points

Minerva uses entity resolution to consolidate source records that are likely to refer to the same subject. Many profile fields therefore include both a representative consensus value and the source observations that contributed to it. For example:

results[i].nationality.value is the representative nationality selected for the resolved candidate.
results[i].nationality.sources[] contains the individual source observations for nationality.

A source observation can include:

Field	Meaning
`value`	Value reported by the source.
`source` and `feed`	Origin of the value and the Minerva feed it belongs to.
`timestamp`	Collection or reporting timestamp when available.
`inferred`	Whether Minerva derived the value algorithmically rather than receiving it directly.
`reputation_score`	General source-reputation score from `0` to `10`.
`trusted`	Whether the reputation score met the trusted threshold.
`match_score`	Closeness of this source value to the submitted search value.
`criteria_match_level`	Human-readable closeness label for this source value.

The consensus is not simply the value reported by the greatest number of sources. Entity resolution considers the available evidence, source reputation, and whether values were directly reported or inferred. When sources disagree, review the complete sources[] array. The number of sources reporting a value is not itself a confidence score.

Identity And Context Field Mapping

Use the following fields to corroborate identity and understand the candidate:

Field	What to review
`name.value` and `name.sources[]`	Candidate name, spelling variants, original values, and supporting sources.
`aliases[]`	Alternative names, transliterations, initials, former names, and non-Latin variants.
`time_begin`	Date of birth for an individual, or incorporation/formation date for an organization.
`alt_times[]`	Other reported dates of birth or incorporation.
`locations[]` and `nationality`	Addresses, cities, states/provinces, countries, and citizenship or country affiliation.
`occupation` and `organization`	Role, title, employer, political party, state-owned enterprise, or other affiliation.
`ID`	Passports, national IDs, driver’s licences, registration numbers, and similar identifiers.
`contact.email[]` and `contact.phone[]`	Known contact information.
`links[]`	Family, business, ownership, employment, political, and other relationships.
`notes[]` and `other_fields`	Source narratives, transcripts, list remarks, and additional contextual attributes.
`documents[]` and `websites[]`	Supporting documents, registry records, filings, corporate sites, personal sites, and references.
`images[]`	Contextual images when a contributing source provides them; absence is common and not a negative signal.

time_begin.value is structured as year, month, and day. Month and day can be absent when a source only provides a year or year-month. Source-specific date observations are in time_begin.sources[]. Identifiers in ID are particularly common when sanctions-list publishers provide passport, national-ID, or registration-number details. Do not assume every source will provide a public identifier.

Source Details, URLs, And Explanations

results[i].sources[] is the concise list of contributing source names. results[i].source_details[] is the richer evidence trail. Each source_details[] item can contain:

Field	Meaning
`name`	Source name.
`source_feed`	Minerva feed associated with the source.
`flagged_feeds[]`	Feeds the source caused to flag.
`description`	Source description or explanation of why a record-specific URL is unavailable.
`urls[]`	Documents or articles associated with the source.
`inferences[]`	Algorithmic classification explanations and the context that supported them.

A URL object can include url, title, source_name, snippet, language, date_time_published, http_status_code, and classification flags. An inference can include feed, reason, field, context, and url. This is especially useful when PEP or another classification was inferred from role or narrative evidence rather than supplied as a direct list label. Some structured sources do not provide a record-specific public URL. In that case, use description, hits_info, sourced-field lineage, identifiers, and notes to understand the evidence trail.

Risk-Specific Review Guidance

Sanctions

Confirm checklist.screen.Sanctions is true.
Review checklist.hits.Sanctions for the triggering list names.
Filter checklist.hits_info[] to feed == "Sanctions".
Compare the source-reported name, date, nationality, locations, and identifiers with the submitted subject.
Review source_details[].urls, ID, field-level sources[], and notes[].

PEP

Confirm checklist.screen.PEP is true.
Review checklist.hits.PEP and the corresponding hits_info entries.
Compare name and identity attributes.
Review occupation, organization, links[], and notes[] for role or relationship evidence.
Review source_details[].inferences[] for the classification reason and supporting context.

When present, pep_level is a tier from 1 to 4, with 1 representing the highest-risk tier. It is separate from the identity match score. A PEP flag is a screening signal for review, not an automatic legal conclusion. An abbreviated PEP result can look like this:

{
  "score": 0.91,
  "pep_level": 2,
  "occupation": {
    "value": "Deputy Minister",
    "sources": [
      {
        "value": "Deputy Minister of Example Affairs",
        "source": "Example Government Biography",
        "feed": "PEP"
      }
    ]
  },
  "checklist": {
    "screen": { "PEP": true },
    "hits": { "PEP": ["Example Government Biography"] }
  },
  "source_details": [
    {
      "name": "Example Government Biography",
      "source_feed": "PEP",
      "flagged_feeds": ["PEP"],
      "inferences": [
        {
          "feed": "PEP",
          "reason": "Political office identified in source text",
          "field": "occupation",
          "context": "Served as Deputy Minister of Example Affairs",
          "url": "https://example.com/biography"
        }
      ]
    }
  ]
}

Here, pep_level describes PEP tiering, while score describes identity-match strength. The occupation lineage and inferences[] explain why the source supported the PEP classification.

News / Adverse Media

Confirm checklist.screen.News is true.
Review checklist.hits.News for contributing publishers or sources.
Filter checklist.hits_info[] to feed == "News".
Review media.risk_urls[] for the qualifying adverse-media articles.
Review each article’s title, URL, snippet, publication date, sentiment flags, and risk-category flags.
Use media.neutral_urls[] as contextual material, not as adverse-media findings.

An article normally enters media.risk_urls[] when it qualifies on both negative sentiment and a supported financial-crime or other relevant risk classification. A negative article that does not qualify on risk can remain in media.neutral_urls[]; negative sentiment alone does not make it an adverse media finding. A News flag still requires an identity check. Confirm that the article concerns the submitted subject rather than a namesake or incidental mention. An abbreviated News result can look like this:

{
  "score": 0.88,
  "checklist": {
    "screen": { "News": true },
    "hits": { "News": ["Example News"] }
  },
  "media": {
    "risk_urls": [
      {
        "url": "https://example.com/article",
        "title": "Example investigation article",
        "source_name": "Example News",
        "snippet": "The subject was named in an investigation...",
        "date_time_published": "2026-01-15T10:30:00Z",
        "flags": {
          "sentiment": ["Negative (High)"],
          "risk": ["Fraud/Bribery/Corruption (Medium)"]
        },
        "http_status_code": 200
      }
    ],
    "neutral_urls": []
  }
}

The article classification explains why News flagged, but the candidate’s identity fields and the article context still determine whether the article is about the submitted subject.

Recommended Analyst Review Order

Confirm which requested feeds flagged in checklist.screen.
Review the overall score and field-level closeness. Confirm that configured thresholds match the organization’s risk appetite.
Compare strong identifiers such as DOB or incorporation date, location, nationality, passport, registration number, or personal ID.
Review the exact sources in checklist.hits and the source-reported values in checklist.hits_info[].
Open source links and read the source description, article context, notes, or inference explanation.
Apply the organization’s policy to classify the candidate as true positive, false positive, unresolved, suppressed, or another supported disposition.

See the Match Scoring Guide before changing thresholds or weights. Changing matching configuration affects which candidates reach review and should be calibrated against representative true-positive, false-positive, and high-volume cases.

Automatic Disposition Annotations (New)

Workspaces with Automatic Disposition enabled for the Direct API channel receive Minerva’s disposition analysis inline on screened potential matches - candidates with at least one flagged feed in checklist.screen:

Field	Meaning
`results[i].review_status`	`unresolved`, `true_positive`, or `false_positive`. Only Full Auto Mode changes it; in Hint Mode it stays `unresolved`.
`results[i].automatic_disposition`	Present only when Full Auto Mode applied the prediction and set `review_status`.
`results[i].disposition_hint`	Advisory prediction returned when the outcome runs in Hint Mode or the analysis completed below the configured threshold.

Both annotation objects share the same shape (prediction, confidence, rationale, analysis_status, evidence_refs, score_summary, risk_flags, signature_version, source, and a bounded error). Clean matches and workspaces without the feature never carry these fields, and dispositions are computed before the response or batch row completes, which adds a few seconds per screened entity. See the Automatic Disposition Guide for the full field reference, reading order, hint and full-auto examples, and the per-request X-Minerva-Automatic-Disposition: skip opt-out header.

Profiles, Search History, And Potential Matches

When an integration uses Minerva profiles for onboarding and ongoing monitoring, the identifier chain is:

External customer ID → Minerva profile ID → search request ID → potential matches

1. List Or Locate Profiles

curl -G "https://api.gominerva.com/clm/v1/profiles" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "page=1" \
  --data-urlencode "perPage=100"

Useful profile filters include:

Filter	Use
`external_id`	Find the Minerva profile associated with an ID from a CRM or customer system.
`name`	Find partial full-name matches.
`date_of_birth`	Filter by profile DOB.
`country`, `nationality`	Filter by residence or citizenship/country affiliation.
`status=potential_match`	Build a profile-level queue of records currently requiring potential-match review.
`flag_names`	Filter by profile flags. Accepts comma-separated names.

The screening flag names are:

screeningSanctionsMatch
screeningPepMatch
screeningAdverseMediaMatch

Comma-separated flag_names values return profiles carrying any listed flag. The response list is result.profiles[]. Use result.profiles[i].id as the Minerva profile_id in search APIs. Do not substitute the integration’s externalId for this internal profile ID. Useful profile summary fields include id, externalId, status, flags[], lastScreenedTime, and monitored.

2. List Searches Associated With A Profile

curl -G "https://api.gominerva.com/v2/search/requests" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "profile_id=<profileId>" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=100" \
  --data-urlencode "sort=desc"

Add feed=Sanctions, feed=PEP, or feed=News to limit the history to searches that included that feed. The response list is requests[]. For each item:

Field	Meaning
`id`	Canonical search `request_id`.
`job_id`	Asynchronous job identifier when one is associated with the request.
`created_at`	Screening request time.
`entities[]`	Submitted subject data, associated profile ID, and requested feeds.
`config`	Search configuration retained with the historical request.

3. Identify Searches With Potential Matches

Search history is request metadata. To find the searches that actually produced potential matches, query the match collection directly:

curl -G "https://api.gominerva.com/v2/search/matches" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "profile_id=<profileId>" \
  --data-urlencode "review_status=unresolved" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=100"

The response contains matches[]. Every item is a stored potential match, and its request_id links to the corresponding item in requests[]. The distinct request_id values therefore identify the profile searches that produced potential matches.

Omit review_status=unresolved to include already reviewed matches.
Add hit=Sanctions, hit=PEP, or hit=News for a feed-specific view.
Use the response pagination object when the profile has more matches than the requested page size.

4. Retrieve Matches For One Historical Search

Use the requests[i].id value as request_id:

curl -G "https://api.gominerva.com/v2/search/matches" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "request_id=<requests[i].id>" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=100"

The potential-match objects are under matches[i] rather than the direct-search results[i]. The field mapping is otherwise the same. For example:

Direct synchronous search: results[i].score
Historical match list: matches[i].score
Direct synchronous search: results[i].checklist.screen.Sanctions
Historical match list: matches[i].checklist.screen.Sanctions

If the integration uses the asynchronous /v1/search batch flow, it can also poll GET /v1/search/{jobid}. Once response is complete, each completed batch item contains its own results[] potential-match array. For persistent profiles and audit history, the profile_id → request_id → /v2/search/matches path is normally the most direct. See Search History for pagination, date-range filters, and the historical request response shape.

Integration Checklist

Store the original request, jobid, searchId or request_id, and profile ID with the case record.
Treat checklist.screen as the risk flag and score as identity-match strength.
Retain hits_info, source_details, sourced-field lineage, identifiers, notes, and URLs so analysts can explain the decision.
Do not treat missing optional inputs or unavailable source fields as automatic contradictions.
Require policy-appropriate human review before final disposition.
Paginate profile history and match lists; do not assume the first page is the complete audit record.
Test threshold changes against known true positives, false positives, transliterations, partial dates, common names, and conflicting identifiers.

API Documentation

Screening - Endpoints

Admin Actions - Endpoints

Profiles - Endpoints

Agent Risk Assessments - Endpoints

Screening Integration Guide

The Screening Response Mental Model

Detect Sanctions, PEP, And News

The `checklist` Hierarchy

Detailed Sanctions Example

Overall Score And Field-Level Closeness

Closeness Labels

Consensus Values And Source Data Points

Identity And Context Field Mapping

Source Details, URLs, And Explanations

Risk-Specific Review Guidance

Sanctions

PEP

News / Adverse Media

Recommended Analyst Review Order

Automatic Disposition Annotations (New)

Profiles, Search History, And Potential Matches

1. List Or Locate Profiles

2. List Searches Associated With A Profile

3. Identify Searches With Potential Matches

4. Retrieve Matches For One Historical Search

Integration Checklist

​The Screening Response Mental Model

​Detect Sanctions, PEP, And News

​The checklist Hierarchy

​Detailed Sanctions Example

​Overall Score And Field-Level Closeness

​Closeness Labels

​Consensus Values And Source Data Points

​Identity And Context Field Mapping

​Source Details, URLs, And Explanations

​Risk-Specific Review Guidance

​Sanctions

​PEP

​News / Adverse Media

​Recommended Analyst Review Order

​Automatic Disposition Annotations (New)

​Profiles, Search History, And Potential Matches

​1. List Or Locate Profiles

​2. List Searches Associated With A Profile

​3. Identify Searches With Potential Matches

​4. Retrieve Matches For One Historical Search

​Integration Checklist

​Related Documentation

The Screening Response Mental Model

Detect Sanctions, PEP, And News

The `checklist` Hierarchy

Detailed Sanctions Example

Overall Score And Field-Level Closeness

Closeness Labels

Consensus Values And Source Data Points

Identity And Context Field Mapping

Source Details, URLs, And Explanations

Risk-Specific Review Guidance

Sanctions

PEP

News / Adverse Media

Recommended Analyst Review Order

Automatic Disposition Annotations (New)

Profiles, Search History, And Potential Matches

1. List Or Locate Profiles

2. List Searches Associated With A Profile

3. Identify Searches With Potential Matches

4. Retrieve Matches For One Historical Search

Integration Checklist

Related Documentation