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

# Screening Integration Guide

> Map Minerva screening responses into compliance review workflows, interpret risk flags and match scores, and retrieve profile-linked search results.

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:

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

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

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

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

### The `checklist` Hierarchy

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

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

1. `checklist.screen.Sanctions` confirms that the Sanctions feed flagged.
2. `score` says the overall candidate is a strong criteria match.
3. `checklist.hits.Sanctions` names the list that triggered the risk finding.
4. The matching `hits_info` item shows the original name, date, nationality,
   and location reported by that list.
5. `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

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

### PEP

1. Confirm `checklist.screen.PEP` is `true`.
2. Review `checklist.hits.PEP` and the corresponding `hits_info` entries.
3. Compare name and identity attributes.
4. Review `occupation`, `organization`, `links[]`, and `notes[]` for role or
   relationship evidence.
5. 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:

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

1. Confirm `checklist.screen.News` is `true`.
2. Review `checklist.hits.News` for contributing publishers or sources.
3. Filter `checklist.hits_info[]` to `feed == "News"`.
4. Review `media.risk_urls[]` for the qualifying adverse-media articles.
5. Review each article's title, URL, snippet, publication date, sentiment flags,
   and risk-category flags.
6. 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:

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

1. Confirm which requested feeds flagged in `checklist.screen`.
2. Review the overall `score` and field-level closeness. Confirm that configured
   thresholds match the organization's risk appetite.
3. Compare strong identifiers such as DOB or incorporation date, location,
   nationality, passport, registration number, or personal ID.
4. Review the exact sources in `checklist.hits` and the source-reported values in
   `checklist.hits_info[]`.
5. Open source links and read the source description, article context, notes, or
   inference explanation.
6. 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](/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.

## Profiles, Search History, And Potential Matches

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

```text theme={null}
External customer ID → Minerva profile ID → search request ID → potential matches
```

### 1. List Or Locate Profiles

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

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

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

```bash theme={null}
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](/api-reference/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.

## Related Documentation

* [Single Search Synchronous API](https://docs.gominerva.com/api-reference/search/single-search-synchronous-api)
* [Search History](/api-reference/search-history)
* [List Profiles](https://docs.gominerva.com/api-reference/profile-management/list-profiles)
* [Match Scoring Guide](/match-scoring-guide)
* [Sanctions](/concepts/sanctions)
* [PEP Policy](/concepts/pep-policy)
* [Adverse Media](/concepts/adverse-media)
* [Data Feeds](/concepts/data-feeds)