# Adverse Media Categories Source: https://docs.gominerva.com/adverse-media-categories How to choose financial and non-financial adverse media risk categories by workspace and screening channel, including per-search API overrides. Adverse media categories describe the type of risk Minerva found in an article. Administrators can choose which categories Minerva is allowed to emit for each screening channel, while API integrations can override that choice for one synchronous search or one entity in a batch. **Access:** Requires the Admin role or above. In the sidebar, go to Administration > Configuration > Adverse Media, then open Adverse Media Risk Classification. Use this guide when you need to: * align adverse media output with your AML, KYC, background-check, or general screening policy * add or remove categories independently across Minerva's four screening channels * understand the distinction between financial and non-financial crime risk categories * preserve a known API response contract while testing newly introduced categories * override the category set for one synchronous search or one entity in a batch Category configuration is workspace-scoped. A Calibration workspace can use a different category set from Live, and changing one workspace does not change another. A risk category is a machine-learning classification of article content, not a finding of guilt, a legal conclusion, or proof that the article concerns the screened subject. Review the identity evidence, source, article context, jurisdiction, dates, and case disposition before making a decision. ## How Category Classification Works Minerva evaluates qualifying adverse media articles for sentiment and one or more supported risk topics. An article can receive more than one risk category when its content supports multiple themes. For example, reporting about a bribery scheme that launders proceeds through real estate can support Fraud/Bribery/Corruption, Money Laundering, and Real Estate. The category configuration is an allow-list: * an enabled category may appear when the model finds enough evidence for it * a disabled category cannot appear in adverse media risk scores or article flags and cannot contribute to screening outcomes * enabling a category does not force Minerva to assign it * disabling a category does not stop article retrieval or disable the News feed * category changes affect subsequent searches and article processing; they do not rewrite completed search results The model's internal no-risk outcome is not a configurable category. ## Financial And Non-Financial Risk The two groups help administrators align the category set with the purpose of a screening program. They are configuration groupings, not legal classifications. ### Financial Crime Risks The Financial Crime Risks group contains 28 AML-relevant themes. Its scope is intentionally broader than money laundering alone and includes: * money laundering, movement of value, concealment of ownership, and sanctions evasion * alleged predicate offences that may generate criminal proceeds, such as fraud, bribery, corruption, narcotics trafficking, human trafficking, smuggling, tax evasion, and organized crime * terrorist activity and terrorist financing * products, services, sectors, and assets that can be abused to move or disguise value, such as cryptocurrency, money service businesses, foreign exchange, real estate, casinos, art, precious materials, auctions, and luxury vehicles These labels help surface media that may be relevant to customer due diligence, enhanced due diligence, transaction-monitoring context, or suspicious activity review. Whether a theme is in scope for a particular AML program depends on the organization's jurisdiction, products, customer base, risk assessment, and procedures. A sector-oriented category does not mean that ordinary activity in that sector is adverse. Minerva assigns risk categories from the article's adverse context, such as laundering through an auction house. It does not assign a category merely because the article mentions an auction. ### Non-Financial Crime Risks The Non-Financial Crime Risks group covers adverse conduct that is useful for background checks, safety reviews, or broader criminal-risk screening but is not, by itself, a financial-crime theme: * Other (Non-Financial) is the legacy catch-all for serious adverse conduct that does not fit a specific financial category * DUI covers impaired-driving offences * Property Damage covers vandalism and other attributed damage to property * Assault and Battery covers physical violence against another person An article may still receive both financial and non-financial categories when the facts support both. For example, an alleged assault connected to an organized-crime enterprise can support Assault and Battery and Organized Crime. ## Default Category Set New and previously unconfigured workspaces preserve Minerva's established 29-category response contract: * all 28 financial crime categories are enabled * Other (Non-Financial) is enabled * DUI, Property Damage, and Assault and Battery are disabled until an administrator enables them This default prevents newly introduced risk-score keys from appearing unexpectedly in customer integrations. Enable a new category only after downstream mappings, reports, rules, and API consumers are ready to accept it. ## Financial Crime Category Reference | Display name | API key | What the category covers | | ------------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------- | | Auctions | `auctions` | Auction-related financial crime, including bid rigging, auction fraud, or value laundering. | | Casinos | `casinos` | Gambling-sector crime, illegal operations, junket risk, or laundering through casinos. | | Cryptocurrency | `cryptocurrency` | Virtual-asset fraud, illicit payments, darknet activity, mixers, or unregistered exchanges. | | Currency Exchanges / Forex | `international_services` | Unlicensed foreign-exchange activity, black-market currency trading, or exchange-based laundering. | | Cybercrime | `cybercrime` | Hacking, ransomware, phishing, account takeover, data theft, or other technology-enabled crime. | | Fine Art | `fine_art` | Art fraud or forgery, cultural-property smuggling, or laundering value through art. | | Foreign Assets | `foreign_ownership` | Hidden offshore accounts, shell structures, unexplained overseas wealth, or high-risk foreign holdings. | | Fraud/Bribery/Corruption | `fraud_bribery_corruption` | Fraud, bribery, corruption, embezzlement, kickbacks, or abuse of position for gain. | | Human Trafficking | `human_trafficking` | Forced labour, sex trafficking, or other exploitation and trafficking of people. | | Insider Trading | `insider_trading` | Trading or tipping on material non-public information, front-running, or insider-led manipulation. | | Lending Services | `loan_companies` | Loan-sharking, predatory or unlicensed lending, and lending-related fraud. | | Luxury Vehicles | `luxury_vehicles` | Laundering through high-value vehicles, stolen-vehicle networks, or related tax fraud. | | Money Laundering | `moneylaundering` | Concealing, layering, integrating, or moving suspected illicit proceeds. | | Money Service Businesses | `third_party_transactions` | Unlicensed remittance, suspicious money transfer, structuring through MSBs, or informal value transfer. | | Narcotics | `narcotics` | Illegal production, trafficking, smuggling, or distribution of controlled substances. | | Non-profit | `non_profit` | Diversion of donations, sham charities, or misuse of non-profit entities to move funds. | | Organized Crime | `organized_crime` | Mafia, cartel, gang, racketeering, or other criminal-enterprise involvement. | | Rare Gems and Metals | `rare_gems_metals` | Conflict minerals, gold or gem smuggling, or laundering through precious materials. | | Real Estate | `real_estate` | Property-related laundering, mortgage fraud, straw buyers, or other real-estate crime. | | Recreational Drugs | `recreational_drugs` | Adverse conduct involving recreational drugs, possession offences, or unlicensed operations. | | Sanctions | `sanctions` | Sanctions evasion, embargo breaches, or trading with designated parties. | | Sex Industry | `sex_industry` | Illegal, exploitative, or financial-crime activity connected with the commercial sex industry. | | Smuggling/Contraband | `smuggling` | Illegal cross-border movement of goods, evasion of customs, or contraband trade. | | Tax Evasion | `tax_evasion` | Concealing taxable income, false returns, offshore evasion, or VAT/carousel fraud. | | Terror Funding | `terror_funding` | Raising, moving, or providing funds for terrorist activity or organizations. | | Terrorism | `terrorism` | Terrorist acts, membership, planning, recruitment, or incitement. | | Used Merchandise | `used_merchandise` | Fencing stolen goods, pawnshop laundering, or counterfeit second-hand trade. | | Weapon Sales/Trade | `weapons` | Illegal firearms sales, arms trafficking, embargo violations, or illicit weapons brokering. | ## Non-Financial Category Reference | Display name | API key | Default | What the category covers | | -------------------------------------- | ----------------- | -------- | ------------------------------------------------------------------------------------------------ | | Other (Non-Financial) | `other` | Enabled | Serious adverse conduct that does not fit one of the specific financial categories. | | Assault and Battery | `assault_battery` | Disabled | Alleged or reported physical violence, including assault, battery, fights, or domestic violence. | | DUI | `dui` | Disabled | DUI/DWI, impaired-driving arrests or charges, and related intoxicated-driving incidents. | | Property Damage | `property_damage` | Disabled | Vandalism, arson-adjacent incidents, collisions, or other attributed property damage. | ## Configure Categories Across Screening Channels The configuration page separates four channels: | Channel | What it covers | | ----------------------------------- | ----------------------------------------------------------------------------------------------- | | Onboarding | Screening performed while a new customer or profile is being onboarded. | | Ongoing Monitoring | Recurring screening for existing profiles. | | Direct API Calls | Synchronous and batch searches submitted with an API application associated with the workspace. | | Risk Assessments | Searches run inside risk-assessment and due-diligence workflows. | To change a workspace: 1. Select the intended workspace, such as Calibration or Live. 2. Open the channel tab you want to change. 3. Check a category to allow it, or clear it to prevent it from being emitted. 4. Use Select all categories only when every downstream consumer can accept all supported keys. 5. Use Restore defaults to return that channel to the standard 29-category set. 6. Repeat the review for each channel that needs a different category set. 7. Select Review changes, confirm the affected channels and categories, add a clear change description, and save. Use History to review prior deployments or restore an earlier configuration. A rollback creates a new history entry and preserves the audit trail. Start with one channel in a Calibration workspace. Compare true-positive retention, false-positive volume, reports, rules, and downstream API mappings before reproducing the approved configuration in Live. ## Override Categories For One API Search The Direct API Calls channel supplies the workspace default for API searches. An integration can replace that default for one call by sending the raw category keys in: ```text theme={null} global_filters.adverse_media_risk_categories ``` Resolution order is: 1. request-level `global_filters.adverse_media_risk_categories` 2. the selected workspace's Direct API Calls configuration 3. the standard 29-category default when no workspace configuration exists A request override can narrow or widen the workspace set. It can therefore enable a category that the workspace leaves disabled. An empty array disables every adverse media risk category for that call. Unknown keys are rejected with an HTTP `400` response that identifies the invalid values. The override changes category emission only. It does not add the News feed or broaden article retrieval, so include `News` in `feeds` when the search should perform adverse media analysis. ### Synchronous Search Place the override in the `POST /v1/search-sync` request body: ```json theme={null} { "type": "individual", "name": "John Smith", "feeds": ["News"], "global_filters": { "adverse_media_risk_categories": [ "moneylaundering", "fraud_bribery_corruption", "sanctions" ] } } ``` See [Search Sync: adverse media risk categories configuration](https://docs.gominerva.com/api-reference/search/single-search-synchronous-api#adverse-media-risk-categories-configuration) for the live request schema. ### Batch Search Place the override inside each applicable object in `requests[]`. Each entity can use a different category set: ```json theme={null} { "requests": [ { "type": "Individual", "name": "John Smith", "global_filters": { "adverse_media_risk_categories": [ "moneylaundering", "fraud_bribery_corruption", "sanctions" ] } }, { "type": "Organization", "name": "Example Holdings", "global_filters": { "adverse_media_risk_categories": [] } } ], "feeds": ["News"] } ``` See [Batch Search: adverse media risk categories configuration](https://docs.gominerva.com/api-reference/search/batch-asynchronous-search-api#adverse-media-risk-categories-configuration) for the live request schema. ## Related Guides * [Adverse Media](/concepts/adverse-media) * [Screening Guide](/screening-guide) * [Match Scoring Guide](/match-scoring-guide) * [Role-Aware Adverse Media Guide](/role-aware-adverse-media-guide) * [Workspaces Guide](/workspaces-guide) # Agent Risk Assessments Guide Source: https://docs.gominerva.com/agent-risk-assessments-guide How to configure, submit, review, collaborate on, and report beta agent risk assessments. Agent risk assessments help teams run structured due diligence workflows with an agent that gathers evidence, updates workflow tasks, summarizes risk findings, and prepares audit-ready review materials. **Beta feature:** Agent risk assessments must be enabled by Minerva before your organization can use them. Contact your Minerva representative or [support@gominerva.com](mailto:support@gominerva.com) to request beta access, workflow setup support, and the API/application access needed for integrations. **Access:** Requires the **Admin** or **Owner** role to configure workflows and client risk rating scorecards. Users with access to the **Risk Assessments** section can create and review assessments according to your tenant configuration. Use this guide when you need to: * configure your first risk assessment workflow * configure a client risk rating scorecard * submit an agent risk assessment with subjects and documents * review risks, task status, evidence, and comments * collaborate with teammates during review * use the relationships canvas for ownership and relationship analysis * generate PDF reports for completed assessments * use the risk assessment history page as a work queue * adapt workflows for KYC, KYB, enhanced due diligence, and custom data source reviews Agent risk assessments are designed for controlled, evidence-backed review. The agent can accelerate research and drafting, but analysts remain responsible for reviewing the evidence, resolving tasks, and concluding the assessment according to internal policy. ## Core Concepts | Concept | What it means | | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | Workflow | A reusable template that defines the assessment purpose, required tasks, enabled tools, and review expectations. | | Assessment | A single run of a workflow for one case, customer, organization, or investigation. | | Subject | An individual or organization assessed in the workflow. Assessments can include primary subjects and related parties. | | Task | A required workflow item that tracks what the agent or reviewer needs to complete. | | Evidence | Documents, web sources, screening results, or generated artifacts registered to support findings and decisions. | | Risk finding | A structured risk observation tied to subjects, tasks, and evidence. | | Client risk rating scorecard | A scoring model that evaluates configured criteria and returns a risk label such as Low, Medium, or High. | | Relationships canvas | A visual workspace for reviewing people, organizations, ownership, control, and relationship edges. | ## Configure Your First Workflow Admins and Owners configure agent risk assessment workflows from tenant configuration. Go to **Administration** > **Configuration** > **Risk Assessment Workflows & Beta**. Start with one workflow that maps to a real operating procedure. A first workflow should be narrow enough that reviewers can tell whether the agent completed the work correctly. Good first workflows usually include: * a clear assessment purpose * one primary subject type, such as individual KYC or organization KYB * a short set of required tasks * the minimum tools needed for the workflow * explicit evidence expectations * a default client risk rating scorecard, if CRR is part of the workflow ### Create A Workflow Select **New workflow template** and choose the closest starting point. Use the workflow name to describe the policy use case, not the customer being reviewed. Examples: | Good workflow name | Why it works | | --------------------------------------- | -------------------------------------------------------------------- | | KYC onboarding review | Clear individual onboarding scope. | | KYB ownership review | Clear organization and ownership scope. | | Enhanced due diligence | Clear higher-risk escalation workflow. | | Custom source review | Clear workflow for organization-specific data source or file review. | Avoid workflow names such as "Test", "New workflow", or a specific customer name. Customer-specific details belong in the assessment title and description. ### Define Workflow Tasks Workflow tasks should match the review steps analysts already perform. Keep tasks specific enough that completion can be evaluated from evidence. Examples: * verify identity or registration details * review sanctions and PEP exposure * review adverse media * assess ownership and control * validate source of funds or source of wealth * complete client risk rating * document open limitations and reviewer decision For each task, define what evidence is expected. This makes the resulting task status and risk findings easier to review. ### Choose Enabled Tools The workflow determines which tools the agent can use. Keep the tool set aligned with the assessment purpose. Common examples: * screening tools for sanctions and PEP review * web research for public source discovery * ownership search for company and officer discovery * document inspection for uploaded onboarding packages or memos * domain write tools that update tasks, notes, evidence, subjects, and comments inside the assessment Do not enable a tool solely because it is available. A smaller tool set is easier to review and audit. ## Configure A Client Risk Rating Scorecard Open the client risk rating configuration from the same risk assessment configuration area. A scorecard defines the factors used to produce a client risk rating. Typical criteria include geography, sanctions or PEP exposure, ownership complexity, source of funds, source of wealth, product risk, adverse media, and custom policy criteria. When creating a first scorecard: 1. Name it after the risk model, such as **Standard KYC CRR** or **KYB EDD CRR**. 2. Add criteria that map to your policy factors. 3. Assign weights that add up to the expected model total. 4. Define score ranges for risk labels such as Low, Medium, and High. 5. Use descriptions to explain what each factor means and what evidence should support the score. 6. Test the scorecard against known low-risk, medium-risk, and high-risk cases. Scorecards are most useful when every criterion can be traced back to evidence. If a factor is important but hard to evidence, write that limitation into the criterion description so reviewers know what to expect. ## Submit An Agent Risk Assessment Open **Risk Assessments** and select **New assessment**. ### Name The Assessment Use a title that helps the history page work as a queue. Good assessment names include: * customer or case name * assessment purpose * date or period if useful * escalation marker when relevant Examples: | Use case | Example title | | ---------------------- | --------------------------------------------------------- | | KYC onboarding | Jane Doe KYC onboarding review | | KYB onboarding | Northstar Holdings KYB onboarding review | | Enhanced due diligence | Ari Vale EDD source of wealth review | | Periodic review | Harbour Retail 2026 KYB refresh | | Escalation or reopen | Cloud Relay ownership gap review | Avoid titles such as "Risk assessment", "Test", or "Customer review". They are difficult to triage later. ### Add Subjects Add the primary subject first. Then add related subjects when the workflow needs them. For individuals, include reliable identifiers when available: * full legal name * date of birth or age range * known aliases * nationality or residence * occupation or role * known addresses For organizations, include: * legal name * registration number * jurisdiction * incorporation or founding date * operating locations * directors, officers, owners, and related entities * known trade names or aliases Structured identity fields help the agent match evidence more accurately and explain uncertainty in the final review. ### Upload Documents Upload documents that the agent should inspect or use as source evidence. Common examples include: * onboarding forms * corporate registry extracts * ownership charts * passports or identity documents, if permitted by your policy * source of funds or source of wealth memos * transaction or account summaries * prior analyst notes * adverse media packets Use descriptive filenames before upload, such as `northstar-ownership-chart-2026-05.pdf` or `jane-doe-source-of-wealth-memo.docx`. Descriptive names make evidence easier to cite later. When uploading documents: * include only documents relevant to the assessment purpose * avoid duplicate or stale versions where possible * add context in the assessment description if a document has limitations * do not rely on uploads alone when policy requires independent corroboration ### Start The Run After the assessment is created, start the agent run. The agent uses the selected workflow, subject details, uploaded documents, and enabled tools to complete tasks and gather evidence. Use the agent trajectory panel to review what the agent did, which tools it called, and where it needs human input. If the agent asks for confirmation or additional input, respond with a clear instruction. If you need the agent to change direction, use steering to add focused guidance, such as: * "Prioritize official registry evidence before media sources." * "Do not conclude source of wealth until the supplied memo is inspected." * "Add the newly discovered parent company as a related subject." * "Re-check adverse media for the Spanish-language alias." ## Review The Assessment Review starts when the agent has enough output for a human analyst to inspect. Depending on the run, the assessment may be running, waiting for user input, ready for review, reopened, concluded, cancelled, or failed. ### Review The Summary The summary view shows subject details, high-level status, risk findings, client risk rating, evidence, and task progress. Use the summary to answer: * What is the assessment trying to decide? * Which subjects are in scope? * Which tasks are complete, incomplete, or require review? * What risk findings are active? * Which findings have evidence? * Is the client risk rating complete or still requiring review? ### Review Risk Findings Risk findings identify material observations discovered during the assessment. For each finding, check: * title and summary * affected subject * severity * task linkage * evidence IDs * source URLs or uploaded document references * whether the finding is active, resolved, or not material * whether the rationale supports the task status Do not mark a task complete only because the agent wrote a summary. Confirm the evidence is sufficient for your policy. ### Update Tasks Tasks are the operational checklist for the assessment. A task can be pending, in progress, complete, incomplete, or requiring review. Use task status deliberately: | Status | When to use it | | -------------------------------- | ------------------------------------------------------------------------------------------------ | | Pending | Work has not started or is waiting behind another task. | | In progress | The task is actively being worked by the agent or reviewer. | | Requires review | The task has output that needs a human decision, evidence check, or policy interpretation. | | Complete | Required evidence and review are sufficient. | | Incomplete | The task cannot be completed with available information and the limitation should be documented. | Use comments or notes when a task status needs explanation, especially for incomplete tasks, manual overrides, or reviewer disagreements. ### Review Client Risk Rating The client risk rating summarizes scorecard criteria and the overall risk label. For each criterion, review: * score and risk label * status * rationale * confidence, when shown * evidence IDs and source URLs * limitations or manual overrides If a score seems unsupported, add a comment and reopen the task or update the assessment before concluding. ## Collaborate Through Comments Use comments for review questions, decision explanations, and handoffs. Comments can be attached to assessment-level review, canvas work, tasks, or scorecard factors depending on the context. Good comments are specific: * "Please confirm whether the Ontario registry extract is current enough for the KYB decision." * "I disagree with Medium ownership risk because the nominee director is still unresolved." * "Source of wealth task can be completed if the uploaded memo is accepted as policy evidence." * "This assessment should remain reopened until the parent entity is added to the relationships canvas." Avoid comments that cannot be acted on, such as "please check" without naming what needs review. ## Use Evidence For Audit Evidence is the audit trail behind the assessment. Evidence can include uploaded files, web sources, screening results, generated artifacts, or dashboard links returned by integrated tools. When reviewing evidence: * open the cited source before accepting a material finding * compare source dates with your policy requirements * check whether evidence supports the exact subject, not just a similar name * confirm uploaded documents are the intended version * cite evidence IDs in notes when making a manual decision * document limitations where evidence is incomplete, stale, or ambiguous Evidence IDs are especially important for audit. They make it possible to trace a task decision, risk finding, CRR criterion, or report statement back to a concrete source. ## Use The Relationships View The relationships view helps reviewers inspect ownership, control, roles, and related-party structure. Use the view to: * review discovered subjects * add or validate ownership and control relationships * distinguish officers, directors, beneficial owners, subsidiaries, and parent entities * flag high-risk subjects in the structure * add comments where the structure needs review * export the relationship graph when it supports the assessment record The canvas is most valuable for KYB, enhanced due diligence, sanctions evasion, nominee ownership, and complex corporate structure reviews. When using the canvas: 1. Start with the primary subject. 2. Add directly known owners, directors, officers, and related entities. 3. Use evidence to support every material relationship. 4. Keep relationship labels specific. 5. Review high-risk subjects and edge context before concluding. 6. Add comments for unresolved links or ownership gaps. 7. Export PNG or PDF from the canvas when the relationship graph should be included in downstream review materials. ## Generate PDF Reports When review is complete, open the assessment **Reports** tab and select **Generate PDF report**. Minerva queues a report job for that assessment. The reports section lets you: * generate a fresh PDF report for the current assessment * review report job status * inspect generated report artifacts * download completed PDF artifacts Generate the report after: * required tasks are complete or documented as incomplete * material risk findings have been reviewed * CRR criteria are complete or explicitly marked for review * comments that affect the conclusion are resolved or summarized * limitations are captured in notes * the assessment status is ready for review or concluded according to your internal process If you change material assessment content after generating a report, generate a new PDF so the artifact reflects the current record. ## Use History As A Work Queue Open **Risk Assessments** > **History** to review your assessment queue. The **My Risk Assessments** tab is useful for: * active work you created * assessments assigned to you by process * items waiting for your input * ready-for-review items you need to finish * reopened assessments that need follow-up The **Team Risk Assessments** tab is useful for: * supervisor review * balancing analyst workload * identifying stale or failed assessments * checking which cases are ready for review * finding concluded assessments for audit or reporting ### Status Triage Use status to decide what to do next. | Status | Queue meaning | Next action | | --------------------------------- | --------------------------------------------------- | ----------------------------------------------------------- | | Draft | Created but not started. | Add missing subjects or documents, then start the run. | | Running | Agent work is in progress. | Monitor only if urgent, or wait for completion. | | Waiting for user | The agent needs input or confirmation. | Open the assessment and respond. | | Interrupted | The run stopped before normal completion. | Review the trajectory and resume or restart as appropriate. | | Ready for review | Agent output is ready for human review. | Review tasks, risks, evidence, CRR, and comments. | | Reopened | A concluded or reviewed assessment needs more work. | Resolve the reopened issue, then move back to review. | | Concluded | Final decision has been recorded. | Generate or download reports when needed. | | Cancelled | Work was cancelled. | Confirm cancellation is intentional and documented. | | Failed | The run failed. | Review error context and contact Minerva if it repeats. | If your tenant has a custom escalation status, treat it as a supervisor or second-line review queue. Use the assessment comments to document who needs to act and why. ### Work Queue Best Practices * Sort by updated time to find stale reviews. * Filter to ready-for-review for analyst completion work. * Filter to waiting-for-user for blocked agent runs. * Review team queue statuses at least daily during beta rollout. * Use consistent assessment titles so queue rows are self-explanatory. * Do not conclude assessments directly from queue context. Open the assessment and review evidence first. ## Example Workflows ### KYC Onboarding Use for individual customer onboarding. Typical workflow: 1. Add the individual as the primary subject. 2. Upload onboarding forms and permitted identity evidence. 3. Enable screening and public source tools required by policy. 4. Ask the agent to verify identity details, sanctions exposure, PEP exposure, and adverse media. 5. Review task output and evidence. 6. Complete the CRR scorecard. 7. Conclude with the onboarding risk decision and generate a PDF report if needed. Recommended tasks: * verify identity details * screen sanctions and PEP * review adverse media * assess source of funds or source of wealth * complete client risk rating ### KYB Onboarding Use for organization onboarding and ownership review. Typical workflow: 1. Add the organization as the primary subject. 2. Upload registry extracts, ownership charts, and onboarding packages. 3. Add known directors, officers, beneficial owners, and parent entities as related subjects. 4. Use ownership search and public source tools to corroborate structure. 5. Review the relationships canvas. 6. Screen the organization and material related parties. 7. Complete the CRR scorecard and document limitations. Recommended tasks: * verify registration details * review ownership and control * screen organization and related parties * assess jurisdiction and product risk * review adverse media * complete KYB CRR ### Enhanced Due Diligence Use for higher-risk customers, escalations, or periodic reviews that require deeper evidence. Typical workflow: 1. Start from the known customer or case name. 2. Add the trigger for EDD in the assessment description. 3. Upload prior case notes and any relevant documents. 4. Enable broader public source, screening, and ownership tools. 5. Require evidence-backed task completion. 6. Use comments for second-line review questions. 7. Generate a PDF report only after reviewer comments and limitations are addressed. Recommended tasks: * confirm escalation trigger * review sanctions, PEP, adverse media, and enforcement exposure * validate source of funds or wealth * review ownership and associates * document residual risk and controls * complete enhanced CRR ### Custom Data Source Review Use when your organization needs the agent to inspect uploaded files, internal exports, or special-purpose data sources. Typical workflow: 1. Create a workflow specific to the source and review purpose. 2. Upload the source documents or data extracts. 3. Explain the source context in the assessment description. 4. Ask the agent to extract relevant facts, register evidence, and update tasks. 5. Review evidence IDs carefully because source interpretation may be policy-specific. 6. Document any source limitations before concluding. Recommended tasks: * inspect uploaded source documents * extract relevant facts and identifiers * compare extracted facts to subject records * identify unresolved discrepancies * document limitations and reviewer decision ## Beta Rollout Checklist Before broad rollout: * confirm Minerva has enabled the beta for the intended tenant and workspaces * configure one pilot workflow and one CRR scorecard * run a small set of known cases through Calibration or a beta workspace * compare agent output to existing analyst review results * document evidence quality expectations * define who can conclude assessments * define when PDF reports should be generated * define queue review cadence * agree how comments, reopened assessments, and custom escalation statuses should be handled ## Related Guides * [Risk Assessment Flow](/risk-assessment-flow) * [Workspaces Guide](/workspaces-guide) * [Screening Guide](/screening-guide) * [Match Scoring Guide](/match-scoring-guide) * [Risk Assessment Agents API](/api-reference/risk-assessment-agents) # Repeated Alert Suppression Guide Source: https://docs.gominerva.com/alert-suppression-guide How to configure repeated alert suppression for monitored profiles and ongoing screening. Repeated alert suppression helps your team reduce repeated sanctions, PEP, and adverse media noise for profiles that stay on ongoing monitoring. **Access:** Requires the **Admin** role or above. In the sidebar, go to **Administration** > **Configuration**, then open **Repeated Alert Suppression** under **Screening Behaviours**. Use this guide when you need to: * understand how repeated monitoring alerts are grouped for the same profile * choose between the built-in suppression presets * create or maintain workspace presets for your operating model * tune the matching rules that control when repeated alerts stay visible or are suppressed * review change confirmations, deployment history, and rollback options Repeated alert suppression is a **Screening** feature. It depends on profiles, because profiles preserve the monitored subject across the initial onboarding screen and every later screening run. **Balanced** is the default repeated alert suppression configuration for every organization. No action is required to turn on Balanced: it is already enabled by default unless your organization has explicitly changed the repeated alert suppression settings. ## Before You Begin * confirm your screening is managed in Minerva with **profiles**, not only as one-off searches through the API * confirm the profiles are actively part of your ongoing monitoring workflow with monitored statuses * confirm you have access to organization-level Screening configuration with role Admin or above * review the Screening Guide if you need a refresher on profile and alert review workflows ## How Repeated Alert Suppression Works Repeated alert suppression is designed for repeated monitoring on the same profile. At a high level, Minerva: 1. uses the profile as the persistent reference for the screened subject 2. compares a new monitoring result to prior matched results for that same profile 3. evaluates the configured rules for name, date of birth, location, adverse media article similarity, and source changes 4. decides whether the new result should stay visible as a fresh alert or be treated as repeat noise This means repeated alert suppression is most useful after the initial onboarding or first screening event. Once a profile exists, Minerva can compare later screening results against that profile's existing monitoring history. Repeated alert suppression does not replace analyst review. It is meant to reduce repeated noise for the same monitored subject while keeping materially different or newly significant results visible. ## Main Configuration Page The Repeated Alert Suppression page combines four ideas in one place: * the global on or off state for suppression * the built-in or organization preset that acts as the baseline * the advanced rule controls that tune repeat-detection behavior * the change-review and history tools used to deploy, audit, and roll back updates ### Preset and Suppression State At the top of the page, Minerva shows: * **Repeated Alert Suppression Enabled**: turns live suppression on or off for the organization * **Ruleset preset**: selects the preset that provides the current baseline * **Current display state**: shows whether the current draft still matches a saved preset or has drifted to **Custom** If you start from a built-in or organization preset and then tune individual controls, the display state can switch to **Custom** even while the draft remains anchored to the original preset for comparison. For most organizations, this section will already show **Repeated Alert Suppression Enabled** with **Built-in: Balanced** selected, because Balanced is the shipped default configuration. ### Workspace Presets In addition to the built-in presets, each workspace can maintain its own reusable presets. Workspace presets let you: * save a custom draft as a reusable preset * rename a preset and update its description * overwrite a preset with the current draft values * delete a preset from the library without deleting the live repeated alert suppression configuration Use preset names and descriptions to capture the operational context, such as: * the risk posture the preset supports * the business unit or review workflow it was designed for * the reason the preset exists ## Built-In Presets Minerva includes three built-in presets. Built-in presets stay fixed. **Balanced** is the default preset and is already enabled for all organizations unless an administrator has changed the configuration. Use the other presets only when you have a clear reason to move away from that default baseline. ### Conservative Use **Conservative** when your team prefers broader analyst visibility and wants to suppress only the clearest repeats. Key behavior: * uses stricter name and location matching so only stronger repeats are grouped * keeps date-of-birth matching tight and still expects exact month and day when both are present * requires more corroborating identity evidence before suppression is allowed * keeps name-only repeat behavior narrow, with a more limited focus on **PEP** noise * keeps adverse media more sensitive by treating **any new article** as alert-worthy and requiring a shared location when both records include one ### Balanced Use **Balanced** when you want the default Minerva posture for repeated sanctions, PEP, and adverse media monitoring noise. Key behavior: * uses moderate name and location matching designed to reduce repeated monitoring noise without grouping too aggressively * keeps date-of-birth checks tight when that information is present * requires meaningful corroborating identity evidence before suppression * applies name-only repeat behavior across **Sanctions**, **PEP**, and **News** * keeps adverse media visible when an article appears materially different, while suppressing closer repeat coverage ### Aggressive Use **Aggressive** when recurring monitoring results create significant repeat noise and you want broader suppression. Key behavior: * uses broader name and location matching so more recurring noise is grouped as repeat activity * allows more date-of-birth flexibility than the other built-in presets * still expects corroborating identity evidence, but is more willing to suppress repeated noise once that evidence is present * applies broader name-only repeat behavior across **Sanctions**, **PEP**, and **News** * treats adverse media most aggressively by suppressing additional article churn after the same subject has already been established ### Shared Defaults Across The Built-In Presets All three built-in presets start with: * a recent-history lookback window for repeat comparison * **Sanctions new-source alert** turned off * **PEP new-source alert** turned off Turn on the new-source alerts only when you want Minerva to re-surface same-identity sanctions or PEP matches after genuinely new source labels appear. ## Understanding Algorithms And Scores Most similarity rules use a normalized score from **0.00** to **1.00**. * a score closer to **1.00** means the two values look more similar * a higher threshold is usually **stricter**, so fewer borderline repeats will be suppressed * a lower threshold is usually **broader**, so more repeated noise may be grouped together ### Algorithm Guidance | Algorithm | What it does | When to use it | | ------------------------------ | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | Exact | Requires the text to match exactly. | Use it when the source data is already standardized and even small spelling or formatting differences should keep results separate. | | Cosine bigram | Compares overlapping two-character patterns. | Use it for a balanced fuzzy match on names or article text that may vary slightly between sources. | | Token jaccard | Compares overlap between whole-word tokens. | Use it when word order or phrasing often changes, especially for multi-part locations. | ### How To Think About Higher And Lower Values * **Similarity thresholds**: higher means stricter matching and usually fewer suppressions * **History window**: higher means Minerva looks farther back and can suppress more recurring noise * **Date-of-birth year window**: higher means more year drift is tolerated * **Minimum corroborating signals**: higher means stronger identity evidence is required before suppression * **Minimum matching locations**: higher means more location corroboration is required * **New-source minimums**: higher means more new sources must appear before a fresh sanctions or PEP alert is shown ## Rule-By-Rule Controls ### History Window Use **Previous searches to scan** to control how far back Minerva looks for prior matched monitoring results. * range: **1 to 10** previous searches * higher values usually suppress more recurring alerts * lower values keep older prior results from influencing the decision ### Name Similarity Use the **Algorithm** and **Similarity threshold** controls to decide how closely a new result name or alias must resemble a prior one before Minerva treats it as the same repeat. * threshold range: **0.00 to 1.00** * higher threshold: stricter name matching * lower threshold: broader name grouping ### Date Of Birth Use these controls when date-of-birth evidence matters to your review process: * **Allowed DOB window (+/- years)**: range **0 to 10** * **Require exact month/day when both are present**: adds a stricter check whenever both records include month and day detail Use tighter settings when date of birth is usually complete and reliable. Use looser settings only when the data sources often carry partial or slightly inconsistent DOB information. ### Location Similarity Use the location controls when geography helps distinguish repeated results for the same subject. * **Algorithm** * **Location similarity threshold**: range **0.00 to 1.00** * **Minimum matching locations**: range **1 to 5** Raise the threshold or the minimum count when you want more geographic corroboration before suppression. ### Strong Identity Use **Minimum corroborating signals** to control how many strong identity signals must align before Minerva allows suppression. * range: **1 to 3** corroborating signals * higher values make suppression more conservative * lower values make suppression easier to trigger ### Name-Only Repeat Use this rule when you want Minerva to suppress repeated name-only noise even when date of birth or location evidence is limited. Controls: * **Name-only repeat threshold**: range **0.00 to 1.00** * **Feeds**: choose from **Sanctions**, **PEP**, and **News** If no feeds are selected, Minerva will not apply the name-only repeat rule until at least one feed is chosen. ### Adverse Media Adverse media has the richest set of controls because Minerva needs to decide both whether the subject looks like the same person or organization and whether the article looks like the same story. Controls: * **Article treatment** * **Subject algorithm** * **Subject similarity threshold** * **Article algorithm** * **Article similarity threshold** * **Require a shared location when both records include one** Article treatment options: * **Any new articles alert**: use this when every new adverse media article should still appear for review * **Only dissimilar articles alert**: use this when near-duplicate coverage should usually be suppressed but materially different stories should remain visible * **No new articles alert**: use this only when repeated article churn should be heavily suppressed after Minerva has already established the same subject ### Sanctions New-Source Alert Use this control when the same monitored identity should alert again only if additional sanctions source labels appear. * status toggle: on or off * **Minimum new sanctions sources**: range **1 to 10** ### PEP New-Source Alert Use this control when the same monitored identity should alert again only if additional PEP source labels appear. * status toggle: on or off * **Minimum new PEP sources**: range **1 to 10** ## Reviewing And Confirming Changes When you click **Review changes**, Minerva does not save immediately. Instead, it shows a grouped confirmation view that helps you verify what is about to change. The review dialog shows: * the number of changes and sections affected * a grouped summary for each rule family * the current value and the new value side by side * a short tone label such as **Will update**, **Will enable**, or **Will disable** * an optional **Change Description** field Use the change description to capture the business reason for the update. That description is then available later in configuration history. ## Deployment History And Rollback The Repeated Alert Suppression page includes a quick **History** preview so you can review recent deployments without leaving the configuration page. Use the preview to: * see the current live deployment first * review older deployments as rollback candidates * preview an older deployment in the current page before committing to it * jump to the full audit history page ### How Rollback Works Rollback is a controlled restore flow, not a destructive undo. When you select an older deployment: 1. Minerva previews that historical configuration in the current page 2. the page remains in preview mode until you cancel or continue 3. if you continue, Minerva shows the grouped rollback review before anything is applied 4. when you confirm, Minerva writes a **new rollback history entry** and makes that restored configuration live Important behavior: * rolling back does not delete prior history entries * the rollback itself becomes part of the audit trail * Minerva will block a rollback when the selected history entry already matches the current live configuration ## Full Audit History Table Use the full history page when you need the complete audit record, not just the recent quick-compare list. The table includes: * **Changed**: when the configuration was saved or rolled back * **Action**: whether the event was an update or a rollback * **Summary**: the key rule or preset changes from that deployment * **Changed by**: the user who performed the action * **Actions**: rollback entry points for older deployments You can also: * filter by actor name or email * filter by **All changes**, **Updates**, or **Rollbacks** * sort by changed time, action, or actor * page through the full history set ## Recommended Tuning Approach If you are configuring repeated alert suppression for the first time: 1. begin by reviewing the existing **Balanced** baseline, since it is already enabled by default 2. change one rule family at a time so the effect is easier to understand 3. add a clear change description whenever you save 4. use history and rollback if a tuning pass proves too broad or too strict This usually produces a cleaner operating model than moving directly to the most aggressive settings. ## Related Guides * Screening Guide * Profiles * Workspaces Guide * Bulk Actions Guide # Create a latest run command Source: https://docs.gominerva.com/api-reference/agent-runtime/create-a-latest-run-command /api-reference/risk-assessment-agents.json post /assessments/{assessmentId}/commands Creates a generic command for the latest assessment-owned run. type accepts input, user_input, steer, steering, resume, cancel, or stop. # Create a run command by run id Source: https://docs.gominerva.com/api-reference/agent-runtime/create-a-run-command-by-run-id /api-reference/risk-assessment-agents.json post /assessments/{assessmentId}/runs/{runId}/commands Creates a generic command for a specific assessment-owned run. # Get assessment agent run by id Source: https://docs.gominerva.com/api-reference/agent-runtime/get-assessment-agent-run-by-id /api-reference/risk-assessment-agents.json get /assessments/{assessmentId}/runs/{runId} Returns a specific assessment-owned agent-runtime run. # Get latest assessment agent run Source: https://docs.gominerva.com/api-reference/agent-runtime/get-latest-assessment-agent-run /api-reference/risk-assessment-agents.json get /assessments/{assessmentId}/run Returns the latest agent-runtime run attached to the assessment. # List latest run commands Source: https://docs.gominerva.com/api-reference/agent-runtime/list-latest-run-commands /api-reference/risk-assessment-agents.json get /assessments/{assessmentId}/commands Lists input, steering, resume, and cancel commands for the latest assessment-owned run. # List latest run trajectory Source: https://docs.gominerva.com/api-reference/agent-runtime/list-latest-run-trajectory /api-reference/risk-assessment-agents.json get /assessments/{assessmentId}/trajectory Lists enriched agent trajectory records for the latest assessment-owned run. # List run commands by run id Source: https://docs.gominerva.com/api-reference/agent-runtime/list-run-commands-by-run-id /api-reference/risk-assessment-agents.json get /assessments/{assessmentId}/runs/{runId}/commands Lists input, steering, resume, and cancel commands for a specific assessment-owned run. # List run trajectory by run id Source: https://docs.gominerva.com/api-reference/agent-runtime/list-run-trajectory-by-run-id /api-reference/risk-assessment-agents.json get /assessments/{assessmentId}/runs/{runId}/trajectory Lists enriched agent trajectory records for a specific assessment-owned run. # Resume a run by run id Source: https://docs.gominerva.com/api-reference/agent-runtime/resume-a-run-by-run-id /api-reference/risk-assessment-agents.json post /assessments/{assessmentId}/runs/{runId}/resume Adds a resume command to a specific assessment-owned run and queues a follow-up turn when agent-runtime can run it. # Resume the latest run Source: https://docs.gominerva.com/api-reference/agent-runtime/resume-the-latest-run /api-reference/risk-assessment-agents.json post /assessments/{assessmentId}/resume Adds a resume command to the latest run and queues a follow-up turn when agent-runtime can run it. # Send user input to a run by run id Source: https://docs.gominerva.com/api-reference/agent-runtime/send-user-input-to-a-run-by-run-id /api-reference/risk-assessment-agents.json post /assessments/{assessmentId}/runs/{runId}/input Adds a user_input command to a specific assessment-owned run. # Send user input to the latest run Source: https://docs.gominerva.com/api-reference/agent-runtime/send-user-input-to-the-latest-run /api-reference/risk-assessment-agents.json post /assessments/{assessmentId}/input Adds a user_input command to the latest run. Use prompt for plain-text instructions and payload or artifact_refs for structured customer context. # Steer a run by run id Source: https://docs.gominerva.com/api-reference/agent-runtime/steer-a-run-by-run-id /api-reference/risk-assessment-agents.json post /assessments/{assessmentId}/runs/{runId}/steer Adds a steering command that changes how the agent should proceed on a specific assessment-owned run. # Steer the latest run Source: https://docs.gominerva.com/api-reference/agent-runtime/steer-the-latest-run /api-reference/risk-assessment-agents.json post /assessments/{assessmentId}/steer Adds a steering command that changes how the agent should proceed on the latest run. # API Keys Source: https://docs.gominerva.com/api-reference/api-keys How to create and manage Minerva API keys and screening workflow webhooks from the Developers page. Minerva API access is managed from the **Developers** page in the Minerva dashboard. **Access:** Requires the **Developer** role or above. In the sidebar, go to **Administration** > **Developers**. Use this guide when you need to: * create a new live or dev application key for an integration * review existing application key prefixes, creators, and last-used activity * deactivate or delete unused keys without affecting other integrations * configure screening workflow webhooks for profile status updates Create a separate application per environment, customer integration, or downstream service. That keeps key lifecycle actions, last-used timestamps, and audit context isolated for each integration. ## Before You Begin * confirm you have a **Developer**, **Admin**, or **Owner** team role * decide whether the integration needs a **Live** or **Dev** application key * prepare a vault or secrets manager to store any newly created API key * if you plan to use webhooks, prepare an HTTPS endpoint that can validate the `x-webhook-key` header ## Developers Page Overview The Developers page combines two integration surfaces: * **API Keys** for issuing and managing application credentials * **Webhooks** for profile status update notifications ## Create A New API Key Minerva creates API keys through named applications. When you select **Create application**, Minerva asks for: * an application name * an optional description so your team knows what the key is used for * the application mode: **Live** or **Dev** ### What To Expect After Creation * each application receives its own key lifecycle and usage tracking * the new plaintext key is shown only once, so store it immediately in your secrets manager * the table then keeps the key prefix, creator, created timestamp, and last used timestamp for later review Use consistent application names such as **Customer Gateway - Prod**, **Customer Gateway - QA**, or **Partner Sync - Sandbox** so lifecycle actions stay obvious in audit and support workflows. ## Manage Existing API Keys Open an application row to review and manage its details. The management view lets you: * update the application name or description * review the current key prefix and historical key records * confirm who created the application * deactivate an application to stop downstream use immediately * reactivate or delete an application when appropriate ## Screening Workflow Webhooks Webhooks are currently for **profile status update** events only. They are intended to support tighter integrations and near-real-time notifications when you use **Screening Workflow Profiles**. Supported profile status values today are: * `potential_match` * `accepted` * `rejected` This is most useful when your internal systems need to react as Minerva profiles move through review outcomes. Webhooks do not replace the screening APIs. They complement a profile-based workflow by notifying your downstream systems when a Minerva profile changes status. ### Create And Manage Webhooks The Webhooks section lets you: * name each webhook destination clearly * choose which profile status values should trigger notifications * copy the generated webhook key for receiver-side validation * test the destination before relying on it in production * edit or delete old destinations as integrations change ## Best Practices * create one application key per integration and environment instead of sharing a single key broadly * rotate or deactivate keys when an integration is retired or ownership changes * store API keys and webhook keys in a secrets manager, not in source control * use webhook names that identify the receiving system and environment clearly * validate the `x-webhook-key` header on every webhook delivery # Send API Result to User Source: https://docs.gominerva.com/api-reference/api-to-ui-integration/send-api-result-to-user /api-reference/core.json post /v1/sendAPIResultToUser **"I have a manual review element to my onboarding flow, and need to send API results that match certain criteria to investigators in the UI for review."** **"I want to assign a specific API result to a user in the MinervaAI user interface for closer inspection."** The sendAPIResultToUser endpoint allows you to direct specific API results into the investigation bins of users in the MinervaAI user interface. API results can be assigned after being completed using the Search and Search Status APIs. The response body of the Search Status API contains the required job and request IDs to perform this action. The user's email in the MinervaAI system is used to identify the user that should receive the API result. The user that you want to send the result to **must be in the same organization as the API key that submitted the search.** If the investigation does not exist, it will be created as a bin in that user's account to hold the API result in. # Append assessment uploads Source: https://docs.gominerva.com/api-reference/assessments/append-assessment-uploads /api-reference/risk-assessment-agents.json post /assessments/{assessmentId}/uploads Adds upload references to an assessment. Raw file bytes are not accepted here; references should point to objects already uploaded through the approved storage path. # Cancel an assessment and cancel the latest run Source: https://docs.gominerva.com/api-reference/assessments/cancel-an-assessment-and-cancel-the-latest-run /api-reference/risk-assessment-agents.json post /assessments/{assessmentId}/cancel Alias for stopping an assessment. This endpoint is idempotent when the assessment is already cancelled. # Conclude an assessment Source: https://docs.gominerva.com/api-reference/assessments/conclude-an-assessment /api-reference/risk-assessment-agents.json post /assessments/{assessmentId}/conclude Concludes an assessment once required tasks are complete and open questions or confirmations are resolved. # Create a risk assessment Source: https://docs.gominerva.com/api-reference/assessments/create-a-risk-assessment /api-reference/risk-assessment-agents.json post /assessments Creates a tenant-scoped draft assessment. Tenant, workspace, and actor fields are derived from the application key. # Get a risk assessment Source: https://docs.gominerva.com/api-reference/assessments/get-a-risk-assessment /api-reference/risk-assessment-agents.json get /assessments/{assessmentId} Returns the full persisted assessment document, including subjects, tasks, evidence, risks, notes, and conclusion state. # Get assessment summary Source: https://docs.gominerva.com/api-reference/assessments/get-assessment-summary /api-reference/risk-assessment-agents.json get /assessments/{assessmentId}/summary Returns compact assessment status, subjects, task counts, client risk rating counts, notes, conclusion, latest run, and timestamps. # Get assessment tasks, notes, and interrupts Source: https://docs.gominerva.com/api-reference/assessments/get-assessment-tasks-notes-and-interrupts /api-reference/risk-assessment-agents.json get /assessments/{assessmentId}/tasks Returns task records, task status counts, notes, open or answered questions, confirmations, and client risk ratings. # List risk assessments Source: https://docs.gominerva.com/api-reference/assessments/list-risk-assessments /api-reference/risk-assessment-agents.json get /assessments Lists risk assessments for the application tenant with status, task status, search, and pagination filters. # Start an assessment agent run Source: https://docs.gominerva.com/api-reference/assessments/start-an-assessment-agent-run /api-reference/risk-assessment-agents.json post /assessments/{assessmentId}/start Starts the assessment by creating an agent-runtime run owned by risk-assessment-svc. # Stop an assessment and cancel the latest run Source: https://docs.gominerva.com/api-reference/assessments/stop-an-assessment-and-cancel-the-latest-run /api-reference/risk-assessment-agents.json post /assessments/{assessmentId}/stop Cancels the latest run, or the supplied run_id, when it belongs to this assessment, then marks the assessment cancelled with an audit comment. # Update assessment title Source: https://docs.gominerva.com/api-reference/assessments/update-assessment-title /api-reference/risk-assessment-agents.json patch /assessments/{assessmentId}/title Updates reviewer-visible assessment title metadata. # Automatic Disposition Guide Source: https://docs.gominerva.com/api-reference/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. 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](mailto:support@gominerva.com) - to get it enabled. ## 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. 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: 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. | 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. ## 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) # List assessment and task statuses Source: https://docs.gominerva.com/api-reference/configuration/list-assessment-and-task-statuses /api-reference/risk-assessment-agents.json get /status-definitions Returns built-in and tenant custom status definitions for assessment and task state rendering. # List client risk rating scorecards Source: https://docs.gominerva.com/api-reference/configuration/list-client-risk-rating-scorecards /api-reference/risk-assessment-agents.json get /crr-scorecards Lists tenant and workspace scoped client risk rating scorecards used by workflows and assessments. # List risk assessment workflows Source: https://docs.gominerva.com/api-reference/configuration/list-risk-assessment-workflows /api-reference/risk-assessment-agents.json get /workflows Lists active, draft, or archived workflows available to the authenticated application tenant. Tenant and workspace are derived from the application key. # Introduction Source: https://docs.gominerva.com/api-reference/introduction An introduction to the Minerva API and its capabilities The Minerva API enables financial institutions and regulated entities to automate and streamline key parts of their anti-money laundering (AML) compliance workflows. It leverages advanced deep learning models to analyze and consolidate information from over 250,000 global sources, covering nearly 1 billion individuals and entities and over 4.5 billion data points. The API provides structured outputs to support screening, investigations, onboarding, and regulatory reporting. ⚠️ **URL Migration Notice:** Legacy `*.minervaai.io` URLs are deprecated. Use the `*.gominerva.com` URLs shown throughout this API reference for all new integrations. ## Getting Access Access to the Minerva API is managed through the Minerva dashboard: * API keys are created and managed from Administration > Developers. This page requires the Developer role or above. * Create separate live and dev applications so each integration has its own key lifecycle, usage history, and owner context. * For additional access or integration requests, please contact [support@gominerva.com](mailto:support@gominerva.com). * Application API keys are not scoped by per-key RBAC permissions. Any application key carries the full API access of the tenant and workspace context it was created in, so isolate integrations by creating separate applications rather than by narrowing a key. * Hosted MCP credentials are the exception: personal access tokens and agent authorizations issued for the [Minerva MCP server](/api-reference/minerva-mcp-guide) do carry an explicit per-token scope list. Those scopes apply to the MCP endpoints only and never widen or narrow an application API key. ### Authentication Schemes Minerva accepts three credential formats. Which one applies depends on the surface you are calling. | Scheme | Credential | Used by | | ----------------------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | x-api-key | Application API key | The screening and reporting endpoints shown throughout this reference. | | Authorization: Api-Key | Application API key | The header to use for newer services such as [Risk Assessment Agents](/api-reference/risk-assessment-agents), which also still accepts the legacy X-Api-Key header for existing integrations. | | Authorization: Bearer | Hosted MCP personal access token | The [Minerva MCP server](/api-reference/minerva-mcp-guide) only. Application API keys are never accepted there. | ## API Overview The Minerva API is organized around two key capabilities: 1. **Profile Management** 2. **Real-Time Risk Assessment** This guide walks through the features and workflows of each. ### 1. Profile Management & Monitoring * Integrate Minerva into onboarding workflows to screen and register customers in a single step. * Keep customer profiles up to date and synchronize data across internal systems and Minerva. * Enable ongoing monitoring for changes in risk status or new matches. * Leverage APIs and webhooks to support investigation workflows, review queues, and keep internal systems in sync ### 2. Real-Time Risk Assessment Minerva screens individuals and entities against global watchlists (e.g. sanctions, PEPs, criminal, terror lists) and adverse media mentions. Results are enriched with supporting evidence and confidence scoring. * **Real-Time Screening:** Instantly screen a single profile synchronously for immediate results. * **Batch Screening:** Submit large batches of profiles to be processed in parallel asynchronously, supporting high-volume operations. * **Generate reports:** Automatically summarize search results and profile data for documentation, audits, or compliance filings. ## Interpreting Screening Results Each object in a search response's `results[]` array is a ranked **potential match**. It is evidence for review, not a confirmed identity match or an automatic compliance conclusion. Use three separate questions when mapping the response into a compliance workflow: | Question | Primary fields | Meaning | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Did a risk feed flag? | `checklist.screen.Sanctions`, `checklist.screen.PEP`, `checklist.screen.News` | Whether Minerva found a qualifying finding for that candidate in the screened feed. | | How close is the identity? | `score`, `match_score_info.`, `.match_score`, `.criteria_match_level`, `aliases[n].match_score` | How closely the candidate resembles the person or organization submitted in the request. This is match strength, not risk severity. | | What supports the result? | `checklist.hits`, `checklist.hits_info[]`, `source_details[]`, `.sources[]`, `notes[]`, `media.risk_urls[]`, `ID`, and related fields | Which source records, original values, identifiers, links, articles, and explanations an analyst should use to decide whether the candidate is a true match. | A match score is not the probability that a subject is sanctioned, politically exposed, or risky. For example, `score: 0.92` means the candidate matched the submitted identity criteria strongly; it does not mean "92% sanctioned." Field-level and alias-level scores describe the one value they sit on. Each name in `aliases[]` carries its own `match_score` and `criteria_match_level` for that alias alone, so scores in one array normally differ and a record can hold one `exact` alias beside several that score `none`. The closest-matching alias carries `matched_query: true` when it also scored above the candidate's primary name. It marks the one name that matched the search best. An alias that scores above the primary name but below another alias does not carry it. Read overall match strength from `score` and `match_score_info`. ### High-Level Sanctions Example The following abbreviated example shows the fields an integration normally uses first. The values are illustrative. ```json theme={null} { "score": 0.94, "checklist": { "screen": { "Sanctions": true, "PEP": false, "News": false }, "hits": { "Sanctions": ["Example Sanctions List"] }, "hits_info": [ { "source": "Example Sanctions List", "feed": "Sanctions", "name": { "value": "Alex Example", "match_score": 0.96, "criteria_match_level": "close" }, "date": { "value": "1982-04-10", "match_score": 1.0, "criteria_match_level": "exact" } } ] }, "source_details": [ { "name": "Example Sanctions List", "source_feed": "Sanctions", "flagged_feeds": ["Sanctions"], "description": "Illustrative official-list record.", "urls": [], "inferences": [] } ] } ``` In this example: 1. `checklist.screen.Sanctions: true` is the direct risk indicator. 2. `score: 0.94` says the candidate is a strong overall criteria match. 3. `checklist.hits.Sanctions` identifies the list that triggered the flag. 4. `checklist.hits_info[]` shows that the name is close and the reported date is exact. 5. `source_details[]` provides the source description, URLs when available, and any supporting inference context. The analyst should still compare all available identifiers and source evidence before dispositioning the candidate as a true positive, false positive, or unresolved. See the [Screening Integration Guide](/api-reference/screening-integration-guide) for the complete response hierarchy, Sanctions/PEP/News mappings, score and closeness interpretation, consensus and source-lineage fields, profile-linked search history, and recommended analyst review order. ## Recommended Report Generation Flow Use `POST /v1/reports` with a `searchResultId` from a previous search. The abbreviated responses below only show the fields you need to carry from one step to the next: `jobid`, `searchId`, `searchResultId`, `index`, and `reports`. ### Single Search Flow **Step 1: Run `POST /v1/search-sync`** Request: ```bash cURL theme={null} curl -X POST https://api.gominerva.com/v1/search-sync \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "individual", "name": "Jane Doe", "feeds": ["Sanctions", "PEP", "News"] }' ``` ```javascript JavaScript theme={null} const response = await fetch("https://api.gominerva.com/v1/search-sync", { method: "POST", headers: { "x-api-key": process.env.MINERVA_API_KEY, "Content-Type": "application/json", }, body: JSON.stringify({ type: "individual", name: "Jane Doe", feeds: ["Sanctions", "PEP", "News"], }), }); const data = await response.json(); ``` ```python Python theme={null} import requests response = requests.post( "https://api.gominerva.com/v1/search-sync", headers={ "x-api-key": MINERVA_API_KEY, "Content-Type": "application/json", }, json={ "type": "individual", "name": "Jane Doe", "feeds": ["Sanctions", "PEP", "News"], }, ) data = response.json() ``` Response: ```json theme={null} { "status": 200, "jobid": "", "searchId": "", "results": [ { "name": { "value": "Jane Doe", "match_score": 1.0, "criteria_match_level": "exact" }, "score": 1.0 }, { "name": { "value": "Jane Doe", "match_score": 1.0, "criteria_match_level": "exact" }, "score": 1.0 } ] } ``` Save `searchId`. For `search-sync`, this value becomes `searchResultId` in the report-generation request. **Step 2: Run `POST /v1/reports` with that `searchId`** Request: ```bash cURL theme={null} curl -X POST https://api.gominerva.com/v1/reports \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "searchResultId": "", "index": 0 }' ``` ```javascript JavaScript theme={null} const response = await fetch("https://api.gominerva.com/v1/reports", { method: "POST", headers: { "x-api-key": process.env.MINERVA_API_KEY, "Content-Type": "application/json", }, body: JSON.stringify({ searchResultId: data.searchId, index: 0, }), }); const reportData = await response.json(); ``` ```python Python theme={null} import requests response = requests.post( "https://api.gominerva.com/v1/reports", headers={ "x-api-key": MINERVA_API_KEY, "Content-Type": "application/json", }, json={ "searchResultId": data["searchId"], "index": 0, }, ) report_data = response.json() ``` Response: ```json theme={null} { "status": 200, "response": "Reports generated", "reports": ["https://storage.googleapis.com/.../Minerva-Report.pdf"] } ``` `index` selects the ranked match from the prior search response: `0` for the top match, `1` for the second match, and so on. ### Batch Search Flow **Step 1: Run `POST /v1/search`** Request: ```bash cURL theme={null} curl -X POST https://api.gominerva.com/v1/search \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "requests": [ { "type": "individual", "name": "Jane Doe" }, { "type": "organization", "name": "Acme Corp" } ], "feeds": ["Sanctions", "PEP"] }' ``` ```javascript JavaScript theme={null} const response = await fetch("https://api.gominerva.com/v1/search", { method: "POST", headers: { "x-api-key": process.env.MINERVA_API_KEY, "Content-Type": "application/json", }, body: JSON.stringify({ requests: [ { type: "individual", name: "Jane Doe" }, { type: "organization", name: "Acme Corp" }, ], feeds: ["Sanctions", "PEP"], }), }); const batchJob = await response.json(); ``` ```python Python theme={null} import requests response = requests.post( "https://api.gominerva.com/v1/search", headers={ "x-api-key": MINERVA_API_KEY, "Content-Type": "application/json", }, json={ "requests": [ {"type": "individual", "name": "Jane Doe"}, {"type": "organization", "name": "Acme Corp"}, ], "feeds": ["Sanctions", "PEP"], }, ) batch_job = response.json() ``` Response: ```json theme={null} { "status": 200, "message": "Requests successfully submitted", "id": "" } ``` Save `id` from this response. This is the batch `jobid` you use to read the completed results. **Step 2: Read the completed batch results** You can use either `POST /v1/searchStatus` or `GET /v1/search/{jobid}`. The examples below use `POST /v1/searchStatus`. Request: ```bash cURL theme={null} curl -X POST https://api.gominerva.com/v1/searchStatus \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "id": "" }' ``` ```javascript JavaScript theme={null} const response = await fetch("https://api.gominerva.com/v1/searchStatus", { method: "POST", headers: { "x-api-key": process.env.MINERVA_API_KEY, "Content-Type": "application/json", }, body: JSON.stringify({ id: batchJob.id, }), }); const batchResults = await response.json(); ``` ```python Python theme={null} import requests response = requests.post( "https://api.gominerva.com/v1/searchStatus", headers={ "x-api-key": MINERVA_API_KEY, "Content-Type": "application/json", }, json={ "id": batch_job["id"], }, ) batch_results = response.json() ``` Response: ```json theme={null} { "status": 200, "response": "complete", "results": [ { "request": { "name": "Jane Doe" }, "searchId": "_0", "results": [ { "name": { "value": "Jane Doe", "match_score": 1.0, "criteria_match_level": "exact" }, "score": 1.0 } ] }, { "request": { "name": "Acme Corp" }, "searchId": "_1", "results": [ { "name": { "value": "Acme Corp" }, "score": 1.0 } ] } ] } ``` Each `results[n].searchId` is entity-scoped. Pick the `searchId` for the subject you want to report on, then pass that value as `searchResultId`. **Step 3: Run `POST /v1/reports` with the batch result `searchId`** Request: ```bash cURL theme={null} curl -X POST https://api.gominerva.com/v1/reports \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "searchResultId": "_0", "index": 0 }' ``` ```javascript JavaScript theme={null} const response = await fetch("https://api.gominerva.com/v1/reports", { method: "POST", headers: { "x-api-key": process.env.MINERVA_API_KEY, "Content-Type": "application/json", }, body: JSON.stringify({ searchResultId: batchResults.results[0].searchId, index: 0, }), }); const reportData = await response.json(); ``` ```python Python theme={null} import requests response = requests.post( "https://api.gominerva.com/v1/reports", headers={ "x-api-key": MINERVA_API_KEY, "Content-Type": "application/json", }, json={ "searchResultId": batch_results["results"][0]["searchId"], "index": 0, }, ) report_data = response.json() ``` Response: ```json theme={null} { "status": 200, "response": "Reports generated", "reports": ["https://storage.googleapis.com/.../Minerva-Report.pdf"] } ``` ## Summary With Minerva's API's you can: * Screen individuals and entities in real time or as part of a batch * Integrate screening and monitoring into onboarding and compliance workflows * Monitor and manage customer profiles over time * Generate audit-ready reports for documentation and regulatory filings * Streamline and scale your AML compliance operations # Single Search Synchronous API (GET) Source: https://docs.gominerva.com/api-reference/legacy/single-search-synchronous-api-get /api-reference/core.json get /v1/search-sync Legacy synchronous single search via query parameters. This GET method is retained for backwards compatibility and simple name-only requests. For new integrations, use the canonical POST /v1/search-sync method, especially when supplying address, date of birth, or personal ID fields. Average completion time varies - full EDD search completes within 45 seconds, Sanctions and PEP searches typically complete in 300ms-3 seconds. All parameters are matched softly using the Minerva scoring algorithm. **New:** matches in this response can include Automatic Disposition annotations - see the `review_status`, `automatic_disposition`, and `disposition_hint` response fields below and the [Automatic Disposition Guide](/api-reference/automatic-disposition-guide). # Minerva MCP Source: https://docs.gominerva.com/api-reference/minerva-mcp-guide How to reach Minerva from coding agents over the hosted MCP server, including per-harness setup, personal access tokens, scopes, and admin enablement. The hosted Minerva MCP server lets a coding agent such as Codex, Claude Code, Kimi, or opencode call Minerva directly. You register one URL in the agent's configuration, run that agent's login command, approve the request in the browser, and the agent stores its own token. There are no hand-pasted credentials in the normal flow. Hosted MCP access is **off by default**. Someone with the **Admin** role or above has to enable it for your organization, and choose which permissions agent tokens may carry, before anyone can connect. See [Admin Enablement](#admin-enablement). **Access:** Enabling hosted MCP for an organization requires the **Admin** role or above. In the sidebar, go to **Administration** > **Configuration**, then open **Authentication** and find **Hosted MCP access**. **If you are connecting an agent:** [Connect Your Coding Agent](#connect-your-coding-agent) · [Personal Access Tokens](#personal-access-tokens) · [Troubleshooting](#troubleshooting) **If you administer an organization:** [Admin Enablement](#admin-enablement) · [Scopes](#scopes) Use this guide when you need to: * connect Codex, Claude Code, Kimi, or opencode to Minerva * authenticate a headless or CI automation that cannot open a browser * understand what the hosted Minerva MCP server exposes and at which URLs * choose the right scopes for an agent instead of granting everything * enable hosted MCP for an organization and decide what agent tokens may do * diagnose why an agent cannot connect or cannot see the data it expects MCP access is a per-user credential, not an application key. The organization, the token's workspace reach, and its permissions all come from the token itself, so an agent can only ever do what the person who authorized it may do. Minerva never accepts an application API key on the MCP endpoints. ## Before You Begin * confirm someone with the **Admin** role or above has enabled the hosted MCP token policy and allowed the scopes your agents need * confirm your own team role meets the **Minimum team role** set in that policy * install a coding agent that supports remote MCP servers over HTTP * decide the token's **reach**: one workspace, or every workspace in the organization. A pinned token can only ever act in the one it names. * for headless use, prepare a secrets manager to hold a personal access token ## Key Concepts | Concept | What it means | | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **MCP** | Model Context Protocol. The convention coding agents use to discover and call external tools. Minerva hosts a server, so no local process is required. | | **Resource URL** | The MCP endpoint an agent connects to. This is the value you register in the agent's configuration. | | **Authorization server** | The OAuth 2.1 endpoints that issue agent tokens. Minerva serves these on the same hostname as the MCP endpoint, so there is only ever one host to allowlist. | | **Scope** | One named permission on a token, such as `screening:search`. A token carries an explicit list of them. | | **Downscoping** | Minerva grants the overlap of what the agent asked for, what the tenant policy allows, and what your role and products permit. Asking for more grants less. | | **Hosted MCP access policy** | The per-organization setting deciding whether MCP tokens may be created at all, the minimum team role, and the full set of scopes any token may ever carry. | | **Personal access token (PAT)** | A bearer token for automations that cannot open a browser. Draws on the same scope catalog, minus the two scopes only browser consent can grant. | | **Entitlement** | Product access granted to an organization, sometimes per workspace rather than across all of it: ID verification is organization-wide, the agent risk assessment beta is per workspace. An entitlement is not a permission, but some scopes require one. | ## The Minerva MCP Server Minerva publishes two resource URLs on the same hostname: | Endpoint | Use it for | | ---------------------------------------- | ------------------------------------------------------------------------------------------------ | | `https://mcp.gominerva.com/mcp` | The full server. Whatever the token's scopes permit, including writes. | | `https://mcp.gominerva.com/mcp/readonly` | The read-only tool subset. Mutating tools are not advertised at all, whatever the token carries. | Prefer the read-only endpoint whenever an agent only needs to look things up. It removes the possibility of an accidental write even if a token is broader than it should be, which makes it the right default for an autonomous agent. You can register both. Most clients allow more than one MCP server, so a common setup is a `minerva` entry pointing at the full endpoint for day-to-day work and a `minerva-readonly` entry for agents you want structurally unable to change anything. Minerva also serves the OAuth 2.1 authorization server on `https://mcp.gominerva.com`, so the discovery documents, the authorize and token endpoints, and the signing keys all live on the same host as the MCP endpoint. If your network policy requires an allowlist, one hostname is enough. Compliant clients discover all of this automatically from `https://mcp.gominerva.com/.well-known/oauth-protected-resource` and `https://mcp.gominerva.com/.well-known/oauth-authorization-server`. You should never need to configure an authorization URL, a client ID, or a client secret by hand: Minerva supports dynamic client registration, so the agent registers itself on first login. ## Connect Your Coding Agent Setup is the same two steps everywhere: register the resource URL, then run the client's login command and approve the request in the browser. ### Step 1: Register The Server Codex, Claude Code, and opencode each write their own manifest entry from the command line. Kimi has no MCP subcommand, so its entry is added to `~/.kimi-code/mcp.json` by hand. ```bash Codex theme={null} codex mcp add minerva --url https://mcp.gominerva.com/mcp ``` ```bash Claude Code theme={null} claude mcp add --transport http minerva https://mcp.gominerva.com/mcp ``` ```bash opencode theme={null} opencode mcp add minerva --url https://mcp.gominerva.com/mcp ``` ```json Kimi theme={null} { "mcpServers": { "minerva": { "url": "https://mcp.gominerva.com/mcp" } } } ``` `codex mcp add` just writes `~/.codex/config.toml`. If you manage your configuration in dotfiles, add the equivalent block directly instead: ```toml theme={null} [mcp_servers.minerva] url = "https://mcp.gominerva.com/mcp" ``` For a read-only agent, use the same commands with a different name and `https://mcp.gominerva.com/mcp/readonly` as the URL. That endpoint advertises only the read-only tool subset, which is the safer default when you are wiring Minerva into an autonomous agent. ### Step 2: Sign In ```bash Codex theme={null} codex mcp login minerva ``` ```bash Claude Code theme={null} claude mcp login minerva ``` ```bash opencode theme={null} opencode mcp auth minerva ``` **Kimi** has no login subcommand. It starts the browser authorization flow the first time the agent connects to the server, so just use Minerva in a session. Each command opens your browser. If you are already signed in to `app.gominerva.com`, you only have to approve the request. **Codex:** hosted MCP login needs codex-cli **0.147.0-alpha.2 or later**. As of July 2026, that is published on npm's `alpha` channel only; no stable release carries it yet. On a stable client (0.146.0 or earlier; check with `codex --version`) the browser approval completes and the login still fails in the terminal with *Authorization server response missing required issuer*, because the client enforces the issuer requirement without reading the issuer from its own callback. That is a client bug, not a Minerva one: until 0.147.0 is stable, [use a personal access token](#personal-access-tokens) with Codex instead. ### Step 3: Approve The Request The consent screen names the client that asked, the workspace the token will act in, and every scope requested. `mcp:read` is preselected and cannot be deselected, because a token without it cannot discover the tools it may call. Deselect anything the agent does not need. [Scopes](#scopes) explains what each one grants. This is the last point at which you choose, and it is per connection, so a research agent and a case-management agent can hold very different permissions under the same account. The figure's example policy offers optional scopes. Your organization's policy can limit which optional scopes appear. When none are available, `mcp:read` is the only scope on offer, and a connection carrying only that can call `whoami` and `list_tool_permissions` and nothing else. That is a working connection, not a failed one. After you approve, Minerva confirms the grant and sends the authorization to your client immediately, then tells you to finish the login in your terminal. A CLI login has just opened its listener and is blocking on it, so the send lands while the client is waiting and the tab hands you back to the client's own confirmation. The figure below is a Codex login. The button on that screen is a fallback, not a step: if your client is still waiting, use it to send the authorization again; if your terminal has already printed success, the login is done and the page is simply left over. A client whose return address cannot be verified gets an error screen instead: **Authorization not sent**. The client is given no access; run the login command again. ## Personal Access Tokens Two kinds of caller need a token rather than a browser sign-in: anything with no browser to open, such as CI jobs, schedulers, and containers, and a developer whose client cannot complete the browser login, which as of July 2026 means Codex on a stable release (see the browser flow's [Step 2: Sign In](#step-2-sign-in)). For both, create a personal access token and send it as a bearer token. It draws on the same scope catalog as a browser sign-in, with one difference that matters: a personal access token cannot carry `mcp:write` or `offline_access`, which only browser consent can grant (see [Scopes](#scopes)). Go to **Administration** > **Developers** and open **Personal access tokens**. The same section is on your account page. Creating a token asks for: * a **name**, so the token is identifiable later in the table * an **expiry** in days, up to a maximum of 90 * **where this token can act**: one workspace, or every workspace in the organization * the **scopes** it carries, offered as the intersection of the tenant policy, your team role, and your organization's entitlements Check the scopes on offer against the work you actually want the agent to do. A token holding only `mcp:read`, which is all a default organization policy allows, connects and authenticates normally but can call just two introspection tools, `whoami` and `list_tool_permissions`: running searches needs `screening:search`, and reading profiles needs `screening:read`. The organization in this example has already allowed the screening scopes. In one that has not, this list shows **Connect and list available tools** on its own. The plaintext token is shown exactly once. Copy it into your secrets manager before closing the dialog; Minerva stores only a hash and cannot show it again. Send it as a bearer token on the MCP endpoint. Every client sends the same header, whatever its own configuration looks like: ```http theme={null} Authorization: Bearer ``` Most clients set that header for you from their configuration rather than making you write it out. The three steps below point Codex at an environment variable holding the token you just copied, so the token itself never reaches the configuration file. ### Step 1: Set The Environment Variable Both ways of registering the server below only name the variable, so set it first: ```bash theme={null} export MINERVA_MCP_TOKEN="" ``` ### Step 2: Register The Server With A Bearer Token Either use the CLI: ```bash theme={null} codex mcp add minerva \ --url https://mcp.gominerva.com/mcp \ --bearer-token-env-var MINERVA_MCP_TOKEN ``` That is the browser flow's [Step 1: Register The Server](#step-1-register-the-server) command with one flag added. Or, if you keep your configuration in dotfiles, write the equivalent block into `~/.codex/config.toml` by hand: ```toml theme={null} [mcp_servers.minerva] url = "https://mcp.gominerva.com/mcp" bearer_token_env_var = "MINERVA_MCP_TOKEN" ``` Neither block holds the token. Both only name `MINERVA_MCP_TOKEN`, so whichever one you copy, the `export` above is the part that has to be in place. ### Step 3: Verify The Connection `codex mcp list` then reports the server as `enabled` with `Bearer token` as its auth. That describes the configuration and not the credential: it reads the same whether or not `MINERVA_MCP_TOKEN` is set. If the variable is not set in the environment the agent itself runs in, Codex connects nothing and every Minerva tool is missing with no error. Check it there rather than in the shell you registered from. Do not run `codex mcp login` on top of this. The token is already the credential, so no browser flow is involved and the client-version problem above does not apply. `codex mcp add` writes `bearer_token_env_var`, which names the variable rather than storing the token, so the token never reaches `~/.codex/config.toml`. Codex does also accept a literal `Authorization` value under `http_headers`, which puts the token in that file, so prefer the environment variable. Set it from your secrets manager where you can: typing the `export` by hand puts the live token in your shell history. Codex refuses the `bearer_token` key outright, with `bearer_token is not supported for streamable_http`. Whatever client you use, keep any file that holds a token out of source control. The token table then tracks each token's prefix, scopes, workspace reach, creation and last-used timestamps, and lets you revoke one without touching the others. No Minerva MCP token lasts longer than **90 days**, so every automation needs a rotation plan before it goes live. A token also acts as you, for as long as it is valid: scope it as narrowly as the automation actually needs, bind it to a single workspace where possible, and revoke it the moment the automation is retired or its owner changes role. A token that reaches the end of its expiry shows as **Expired**, not **Revoked**. Nobody has to have withdrawn your access for this to happen, so read the status before assuming someone did. ### When To Prefer A Token Over The Browser Flow | Prefer a personal access token | Prefer the browser login | | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | | CI jobs, schedulers, and containers with no interactive browser | A developer working at a terminal on their own machine | | A developer on a client whose browser login is broken, such as Codex on a stable release | A developer whose client can complete the browser login | | A client that does not implement OAuth dynamic client registration | Any client that supports remote MCP servers properly | | An unattended automation with a fixed, audited scope set and a rotation schedule | Short-lived, exploratory, or ad-hoc agent sessions | | An environment where you must control credential rotation yourself | Cases where automatic token refresh is preferable to managing a secret | ## Admin Enablement Hosted MCP access is **off by default**. Before anyone in an organization can connect an agent, someone with the **Admin** role or above has to turn it on and choose what agent tokens may do. This is the gate that matters, and it is almost always the reason a connection attempt fails. Go to **Administration** > **Configuration** > **Authentication** and open **Hosted MCP access**. Three settings matter: * **Allow users to create hosted MCP personal access tokens** is the master switch for the organization; the other two settings only matter once it is on. * **Minimum team role** is the lowest team role permitted to hold an MCP token. Defaults to **Developer**. * **What tokens may do** is the complete set of scopes any token in this organization may ever carry, grouped by product area, and explained in [Scopes](#scopes). A new policy allows only `mcp:read`. This list is a ceiling, not a grant. When someone creates a token they choose from this list, narrowed again by their own team role and by the products your organization has. Allowing a scope here never gives it to anyone who could not otherwise hold it. Leaving **Minimum team role** at **Member** while allowing administration scopes does not widen access, because each scope also carries its own role floor. The panel names any allowed scopes that sit above the policy minimum. That is informational, not an error. Start by allowing only the connection and screening read scopes, confirm one agent connects, then add scopes as real workflows need them. Because Minerva downscopes rather than failing, a narrow policy produces a working agent with fewer tools instead of a login error. ## Scopes A token carries an explicit list of scopes. Most need a team role, and some also need an organization entitlement, with one wrinkle for the workspace-scoped ones, described under the table. | Scope | Requires, and what it allows | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | `mcp:read` | **Member.** Confirm which account and workspace the token acts in, and list the tools it can call. | | `mcp:write` | **Browser consent only.** Write access across screening, risk, and identity verification. It never grants administration. | | `screening:search` | **Member.** Run new searches against sanctions, PEP, and adverse media. Searches count against your organization's usage. | | `screening:read` | **Member.** Read search results, profiles, potential matches, and profile comments. | | `screening:write` | **Member.** Create and edit profiles, set profile and potential-match status, and add profile comments. | | `risk:read` | **Member + agent risk beta.** Read risk assessments along with their tasks, subjects, and comments. | | `risk:write` | **Member + agent risk beta.** Create and edit risk assessment tasks, subjects, and comments. | | `idv:read` | **Member + ID verification.** Read identity verification sessions and the status of each check. | | `idv:write` | **Member + ID verification.** Start, resend, and cancel identity verification sessions. | | `admin:team` | **Admin.** Read who belongs to this organization and the team role each person holds. | | admin:config\_read | **Admin.** Read workspace and organization configuration settings. | | admin:config\_write | **Admin.** Change workspace and organization configuration settings. | | `offline_access` | **Browser consent only.** Stay connected without signing in again until access is withdrawn. | **Browser consent only** means a client can request the scope during browser sign-in, but it can never be put on a personal access token. `mcp:write` does not bypass anything: a write it covers still needs whatever entitlement the specific scope needs, so it reaches risk assessments only in an organization that has the agent risk assessment beta, and identity verification only where ID verification is enabled. ### How Scopes Are Narrowed Minerva advertises the whole catalog above, and most agents request everything a server advertises on first login. That is expected and is not an error. Minerva grants the intersection of: 1. what the agent requested, 2. what the tenant token policy allows, 3. what your team role and your organization's entitlements permit. The token response reports the scopes that were actually granted. A Member in an organization that allows only screening scopes therefore ends up with a working connection that has screening tools and no administration tools. That is not a failed login. Check the granted scope list, not the requested one, when an expected tool is missing. A few entitlements are granted per workspace rather than per organization (today the agent risk assessment beta), and the scopes that need one behave differently depending on the token's reach. A token that acts in **every** workspace always carries `risk:read` and `risk:write` if the policy and your role allow them. There is no single workspace to check the beta against when the token is issued, so the check happens on each call instead, against the workspace that call names. The same token therefore succeeds in a workspace that has the beta and is refused in one that does not. A token **pinned** to one workspace carries them only if that workspace holds the beta. So pinning does not get you more capability: it gets you less, and more predictably. The reason to pin is blast radius, not reach. Refused risk calls are therefore about the workspace you are calling into, not about the token. See [Troubleshooting](#from-an-agent-call). ## Troubleshooting ### In The Browser | Symptom | Cause and fix | | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | *Personal access tokens are disabled for this organization* | Your administrator has not enabled Hosted MCP access. It is off by default. Someone with the **Admin** role or above turns it on under **Configuration** > **Authentication** > **Hosted MCP access**. | | *Personal access tokens require the … role or higher* | Your team role is below the policy's **Minimum team role**. Ask an Admin to lower the minimum, or to raise your team role. | | *Nothing in this organization’s token policy is available to you* | The policy allows only scopes your role or your organization's products cannot carry. An Admin adds scopes you can hold, or Minerva enables the missing entitlement. | | The consent link fails before you can approve | The authorization request expired, or was already used because the login ran twice. Re-run the login command from the client so it starts a fresh request. | | `429` with an **empty** response body (`server: awselb/2.0`, no content-type) | The edge rate limit: 100 requests per 300 seconds per source IP, one bucket shared by `/oauth/register`, `/oauth/token`, and `/oauth/revoke`, any method. Blocked attempts still count toward the rate, so a tight loop that keeps re-flooding restarts the clock, and a slow one tells you nothing; left alone, the block lifts once the rate falls below the limit. Stop sending requests to those three paths for about five minutes, plus a short detection lag, then try **once**; an occasional attempt does not restart the clock. The limit can also engage a few minutes after you exceed it, so the block may appear later than the burst that caused it. | | `429` with a **JSON** error body and an `x-request-id` | The application registration limit: 20 client registrations per source IP per hour, and it covers only `/oauth/register`. Reuse your existing client registration, or wait out the hour. | | Codex login fails with *Authorization server response missing required issuer* after the browser approval | A codex-cli bug, not a Minerva one: stable clients (0.146.0 or earlier) enforce the issuer requirement without reading the issuer from their own callback, and Minerva correctly sends it. Use a personal access token, or codex-cli 0.147.0-alpha.2 or later (currently the npm `alpha` channel). | Both rate limits key on your source IP, so a shared office or CI egress can trip them without anyone misbehaving. Neither one touches existing tokens, tool calls, discovery, or the authorization step itself: those keep working while new logins are throttled. A greyed-out **Create token** button has two different causes, and the message on screen tells you which. This one shows *Personal access tokens are disabled for this organization*, meaning nobody here has hosted MCP access yet: And this one shows *Personal access tokens require the … role or higher*, meaning the organization has enabled it but your own team role sits below the minimum the policy sets, which is a different fix: And this is the same organization from the admin's side, where the switch is turned off: A browser that opens the consent URL without a usable authorization request gets one of two screens, and which one tells you what went wrong. If the request id is **well formed but no longer good** (the link expired, or it was already used because the login ran twice), you get the invalid-request screen. Re-run the login command from the client so it starts a fresh request. If there is **no request id at all, or a malformed one** (a hand-typed URL, or a link truncated in a chat message), you get an install landing page instead. It repeats the endpoints and carries copy-paste snippets for some clients, but it cannot complete a login on its own, and the commands earlier in this guide are the authoritative set. ### From An Agent Call The three refusal codes an agent can meet (`validation_error`, `workspace_forbidden` and `entitlement_required`) are **authorization outcomes, not transport failures**. Minerva returns them as ordinary MCP tool results: HTTP `200` with `isError: true`, and the code, the message, and a `retryable` flag in the JSON inside `content[0].text`. A `401` therefore means authentication failed, while these mean the call was understood and refused. `validation_error` and `entitlement_required` are never retryable, and neither is a genuine `workspace_forbidden` refusal: the one retryable case is the service-problem form of `workspace_forbidden`, which says so in its message and sets `retryable: true`. | Symptom | Cause and fix | | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **No** Minerva tools at all, and no error | The client never connected, so no scope change will bring the tools back. On a personal access token using `bearer_token_env_var`, the usual cause is that the variable is not set in the environment the agent itself runs in. Check it there rather than in the shell you ran `codex mcp add` from. This is almost never downscoping: any token that carries `mcp:read` keeps `whoami` and `list_tool_permissions`, so if even those two are missing, scopes are not what removed them. | | **Some** Minerva tools, but not the one you expected | Downscoping: that scope was requested but not granted. Compare the granted scopes against the policy, your role, and your entitlements. If the policy is narrower than the work genuinely needs, ask an admin to widen it for that scope rather than in general. | | `401` after the connection previously worked | The access token expired, and refresh only happens if `offline_access` was granted. Re-run the client's login command. For a personal access token, create a new one and update your secret. | | The agent sees no data, or not the data you expected | Check the token's reach. A pinned token acts only in the workspace it names, and a tool argument naming a different one is refused rather than honoured. A tenant-wide token acts wherever the call says, so look at the workspace the call named. | | *this token is not bound to a workspace, so workspace\_id is required …* | `validation_error`. The token acts in every workspace, so it cannot infer a target: each call has to name one. Expect this to be the first error an agent hits with a tenant-wide token, because nothing tells a model to pass a workspace until something does. `list_workspaces` is deliberately callable without a workspace so the agent can discover the ids, then retry with one named. | | *workspace\_id does not match the workspace this token is bound to …* | `validation_error`. The token is pinned to one workspace and the call named a different one, which Minerva refuses rather than honours. Omit `workspace_id` so the pin applies, or use a token that is not bound to a single workspace. | | *workspace\_id must be a valid workspace identifier …* | `validation_error`. The call named something that is not shaped like a workspace id at all. The usual case is a model inventing one. Call `list_workspaces` and pick a real id. | | *workspace `` is not available to this token …* | **`workspace_forbidden`, not retryable.** The named workspace is not one this token can act on. Minerva answers unknown, archived, and other-tenant workspaces identically on purpose, so this does not tell you which. Call `list_workspaces` to see what the token can reach. Retrying the same call gets the same answer. | | *workspace access could not be verified just now; this is a service problem, not a refusal …* | **`workspace_forbidden`, retryable.** Minerva could not reach the entitlement service, so nothing was learned about the workspace either way, and the payload sets `retryable: true`. Retry the call; if it persists, the problem is on Minerva's side, not the token's. | | *agent risk assessment … is not enabled for workspace ``* | `entitlement_required`. The agent risk assessment beta is granted per workspace, and Minerva checks it on each call against the workspace that call names. The token is not the problem, and the same token can call the tool in a workspace that has the beta. Confirm the beta is enabled on that workspace, or direct the call at one that has it. | | The same not-enabled message on **every** workspace you try | Also `entitlement_required`. A tenant-wide token is issued `risk:read` and `risk:write` without a workspace to check the beta against, so it can carry them in an organization where no workspace currently has it: most often one that had it, had an admin allow the scopes, and later lost it. The token is not broken. Ask an admin to confirm the beta is still enabled where you need it. | | An application API key is rejected on the MCP endpoints | Application keys are never accepted on MCP, by design. Use the browser login or a personal access token instead. | On opencode, two commands help isolate an authorization problem: ```bash theme={null} # OAuth-capable servers and their auth status opencode mcp auth list # debug the OAuth connection for one server opencode mcp debug minerva ``` ## Best Practices * use `https://mcp.gominerva.com/mcp/readonly` for any agent that does not need to write, instead of relying on scopes alone * grant one connection per purpose rather than one broad connection reused everywhere, so revoking an agent does not disturb the others * bind tokens to a single workspace unless an automation genuinely spans all of them * keep the tenant policy as the ceiling you actually intend, and widen it in response to real workflows rather than in advance * prefer the browser login for people, and reserve personal access tokens for automations that truly cannot open a browser * store personal access tokens in a secrets manager, never in source control or in an agent configuration file committed to a repository * schedule rotation before the 90-day ceiling rather than discovering it when a pipeline fails * review the token table periodically and revoke tokens whose last-used timestamp shows they are no longer needed * remember that an agent inherits its authorizer's permissions, so review team roles when someone changes job ## Related Guides * [API Keys](/api-reference/api-keys) * [SAML SSO and SCIM Guide](/authentication-sso-scim-guide) * [Workspaces Guide](/workspaces-guide) * [API Introduction](/api-reference/introduction) # Update Potential Match Status Source: https://docs.gominerva.com/api-reference/potential-matches/update-potential-match-status /api-reference/profiles.json patch /v2/search/matches/{match_id} Updates the review status of a potential match returned by a search. Use this endpoint after an analyst or downstream workflow has reviewed a search result and needs to record the disposition. Supported `review_status` values: - `unresolved`: the potential match still needs review. - `true_positive`: the potential match has been confirmed as a true match. - `false_positive`: the potential match has been determined not to match the screened profile. - `suppressed`: the potential match is a repeated or previously known result with no material change. - `closed`: the potential match is closed and no longer part of the active review queue. - `reopened`: the potential match has been reopened for review. # Profile Custom Fields API Source: https://docs.gominerva.com/api-reference/profile-custom-fields Send and retrieve organization-defined profile values through the Profiles API. Use profile custom fields to exchange organization-specific profile data through the Minerva Profiles API. Definitions belong to your organization and apply across all its workspaces. Requests use immutable definition keys, while responses include both keys and customer-facing labels. For administrator workflows, batch uploads, list columns, and profile views, see the [Profile Custom Fields Guide](/profile-custom-fields-guide). This capability is not yet released to production. The Profiles API, dashboard stories, and this documentation are being prepared together. Do not deploy an integration until your Minerva technical contact confirms that the feature is available for your organization. ## Prerequisites and key discovery You need an application API key for the target organization and workspace. Send it in the `x-api-key` header. An administrator creates definitions under **Administration** > **Configuration** > **Profile Custom Fields**. Record each definition's immutable key and, for Choice fields, each option's stored value. Use keys in requests. Do not use labels as JSON property names because labels can be renamed. ```http theme={null} x-api-key: YOUR_API_KEY ``` The examples below use `https://api.gominerva.com/clm/v1`. See the [API Reference](/api-reference/introduction) for authentication and generated endpoint pages. ## Request contract `profileCustomFields` is a JSON object whose property names are definition keys. Each value must use the JSON type required by that definition. ```json theme={null} { "profileCustomFields": { "loan_number": "LN-2026-0042", "loan_status": "funded", "servicing_details": { "portfolio": "Prime", "boardingDate": "2026-08-27" } } } ``` Use the object on these operations: | Operation | Behavior | | ----------------------------- | --------------------------------------------------------------------------------------------------------- | | `POST /profiles` | Creates a profile without an initial screen. All required custom fields must be present and non-null. | | `POST /onboarding/profiles` | Creates and screens a profile. All required custom fields must be present and non-null. | | `PATCH /profiles/{profileId}` | Updates only the custom keys supplied. Omitted custom keys are preserved. `null` clears one stored value. | On create or onboarding, `null` is equivalent to omitting an optional custom value and fails validation when the field is required. A PATCH validates the custom fields supplied in that request. Custom fields omitted from the request remain unchanged, and `null` clears one named value. Required custom fields that are not included are not checked again. Writes use the latest definitions. An archived or unknown key, a wrong JSON type, an invalid Choice value, or an invalid Date returns HTTP 400. If Minerva cannot retrieve the definitions, it rejects the write instead of saving an unvalidated value. Fetch the latest definitions before sending values, and treat configuration changes as an integration contract change. ### Type matrix | UI label | API `type` | Request JSON value | Example | | --------------- | ---------- | ------------------------------- | ----------------------- | | Text | `text` | String | `"LN-2026-0042"` | | Number | `number` | JSON number, integer or decimal | `4417723` or `12.75` | | Date | `date` | String in `YYYY-MM-DD` format | `"2026-08-27"` | | Yes/No | `boolean` | Boolean | `true` | | Choice | `enum` | Configured stored option value | `"funded"` | | Structured data | `json` | JSON object or array | `{"portfolio":"Prime"}` | Text values support up to 4,000 characters. Structured data must be an object or array and is limited to 16 KB per field. The combined custom values on one profile are limited to 64 KB. Exact integral Number values are accepted through the signed 64-bit range. Choice requests use the option's stored value, such as `funded`, not its display label, such as `Funded`. After a Choice definition is saved, each existing option value remains valid and cannot be changed or removed in this release. Administrators can add options, change display labels, and reorder options. This preserves the identifiers already stored on profiles so historical values remain readable. If the vocabulary must be replaced, contact [Minerva Support](mailto:support@gominerva.com). Archiving the field and creating a new one is another option, but the new field starts empty and does not inherit existing profile values. ### Create a profile ```bash cURL theme={null} curl -X POST "https://api.gominerva.com/clm/v1/profiles" \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "name": "Alex Morgan", "kind": "individual", "profileCustomFields": { "loan_number": "LN-2026-0042", "loan_status": "funded", "servicing_details": { "portfolio": "Prime", "boardingDate": "2026-08-27" } } }' ``` ```javascript JavaScript theme={null} const response = await fetch("https://api.gominerva.com/clm/v1/profiles", { method: "POST", headers: { "x-api-key": process.env.MINERVA_API_KEY, "Content-Type": "application/json", }, body: JSON.stringify({ name: "Alex Morgan", kind: "individual", profileCustomFields: { loan_number: "LN-2026-0042", loan_status: "funded", servicing_details: { portfolio: "Prime", boardingDate: "2026-08-27", }, }, }), }); if (!response.ok) { const error = await response.text(); throw new Error(`Minerva API returned ${response.status}: ${error}`); } const data = await response.json(); console.log(data.result.profile.id); ``` ### Create and screen a profile Use `POST /onboarding/profiles` when profile creation should also perform the configured onboarding screen. ```bash cURL theme={null} curl -X POST "https://api.gominerva.com/clm/v1/onboarding/profiles" \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "name": "Alex Morgan", "kind": "individual", "profileCustomFields": { "loan_number": "LN-2026-0042", "loan_status": "funded", "servicing_details": { "portfolio": "Prime", "boardingDate": "2026-08-27" } } }' ``` ```javascript JavaScript theme={null} const response = await fetch( "https://api.gominerva.com/clm/v1/onboarding/profiles", { method: "POST", headers: { "x-api-key": process.env.MINERVA_API_KEY, "Content-Type": "application/json", }, body: JSON.stringify({ name: "Alex Morgan", kind: "individual", profileCustomFields: { loan_number: "LN-2026-0042", loan_status: "funded", servicing_details: { portfolio: "Prime", boardingDate: "2026-08-27", }, }, }), }, ); if (!response.ok) { const error = await response.text(); throw new Error(`Minerva API returned ${response.status}: ${error}`); } const data = await response.json(); console.log(data.result.profile.id, data.result.tasks); ``` ### Update or clear values PATCH updates only the profile fields and custom field keys supplied in the request. Omitted custom fields remain unchanged, and `null` clears one named value. ```bash cURL theme={null} curl -X PATCH \ "https://api.gominerva.com/clm/v1/profiles/66c391b92888a0db5cc6d3f6" \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "profileCustomFields": { "loan_status": "paid_out", "servicing_details": null } }' ``` This changes Loan Status, clears Servicing Details, and preserves Loan Number and every other custom value. ```javascript JavaScript theme={null} const profileId = "66c391b92888a0db5cc6d3f6"; const response = await fetch( `https://api.gominerva.com/clm/v1/profiles/${profileId}`, { method: "PATCH", headers: { "x-api-key": process.env.MINERVA_API_KEY, "Content-Type": "application/json", }, body: JSON.stringify({ profileCustomFields: { loan_status: "paid_out", servicing_details: null, }, }), }, ); if (!response.ok) { throw new Error(`Minerva API returned ${response.status}`); } ``` ## Response contract Single-profile and list responses can include an optional `profileCustomFields` array. Items are ordered by definition priority. Profile reads may take up to 60 seconds to reflect a definition edit or archive. During that period, `GET /profiles/{profileId}`, `GET /profiles`, and dashboard read views may return the prior field or Choice option label, or may still include a newly archived field. Stored profile values do not change. After the read view refreshes, renamed labels are updated and archived fields are omitted. Profile writes always validate against the latest definition. ```json theme={null} { "msg": "OK", "result": { "profile": { "id": "66c391b92888a0db5cc6d3f6", "name": "Alex Morgan", "profileCustomFields": [ { "key": "loan_number", "label": "Loan Number", "type": "text", "value": "LN-2026-0042" }, { "key": "loan_status", "label": "Loan Status", "type": "enum", "value": "funded", "valueLabel": "Funded" }, { "key": "servicing_details", "label": "Servicing Details", "type": "json", "value": { "portfolio": "Prime", "boardingDate": "2026-08-27" } } ] } }, "status": 200 } ``` For Choice fields, `value` is the stable stored option value and `valueLabel` is the display label resolved for that response. Store or compare `value`; render `valueLabel` when present. After an administrator changes a field label or Choice option label, profile reads can return the previous label for up to 60 seconds. Profile writes always validate against the latest definition. The list operation returns the same optional array on each item: ```json theme={null} { "msg": "OK", "result": { "profiles": [ { "id": "66c391b92888a0db5cc6d3f6", "name": "Alex Morgan", "profileCustomFields": [ { "key": "loan_number", "label": "Loan Number", "type": "number", "value": 9223372036854775807 }, { "key": "loan_status", "label": "Loan Status", "type": "enum", "value": "funded", "valueLabel": "Funded" } ] } ], "meta": { "page": 1, "perPage": 20, "total": 1 } }, "status": 200 } ``` Large integral Number values are emitted exactly as JSON numbers. JavaScript's default `JSON.parse` rounds integers above `Number.MAX_SAFE_INTEGER` (`9007199254740991`). Use a lossless JSON parser before converting the response to JavaScript values. When a business identifier does not need arithmetic, define it as Text at the integration boundary instead. The Minerva API still requires a JSON number for fields whose definition type is Number. ## Validation errors The response follows the standard Minerva error shape, and the message identifies the custom field path when available. For profile writes, HTTP 400 means the request is malformed or a value does not match the current definition; correct the request before retrying. HTTP 409 means a Text value exceeds 4,000 characters, a Structured data value exceeds 16 KB, or the combined custom values exceed 64 KB; shorten the values before retrying. Separately, a definition-management request returns HTTP 409 if it omits or changes a saved Choice option value. Retain the complete saved Choice set, with any additions or label and order changes, before retrying that request. Common failures include: | Failure | Status | Example | Correction | | ----------------------------------- | ------ | ----------------------------------- | ------------------------------------------------------------------------- | | Malformed JSON | 400 | Missing comma or closing brace | Correct the JSON document before retrying. | | Unknown or archived key | 400 | `profileCustomFields.old_status` | Refresh active definitions and stop sending the retired key. | | Wrong JSON type | 400 | `"amount": "125.50"` for Number | Send `125.50` as a JSON number. | | Invalid Date | 400 | `"closing_date": "08/27/2026"` | Send `"2026-08-27"`. | | Invalid Choice | 400 | `"loan_status": "Funded"` | Send the stored option value, such as `"funded"`. | | Missing required value on create | 400 | `loan_number` omitted | Include a non-null value in create or onboarding. | | Invalid Structured data | 400 | `"servicing_details": "Prime"` | Send a JSON object or array. | | Text exceeds 4,000 characters | 409 | `loan_notes` has 4,001 characters | Shorten the Text value, then retry. | | Structured data exceeds 16 KB | 409 | `servicing_details` exceeds 16 KB | Shorten the object or array, then retry. | | Combined custom values exceed 64 KB | 409 | `profileCustomFields` exceeds 64 KB | Remove or shorten custom values, then retry. | | Existing Choice value omitted | 409 | Definition update omits `funded` | Keep `funded`; change its label or order, and add new values when needed. | Example error handling: ```javascript JavaScript theme={null} const response = await fetch( "https://api.gominerva.com/clm/v1/profiles", options, ); if (response.status === 400) { const error = await response.json(); console.error( "Correct the profile custom field request before retrying", error, ); } else if (response.status === 409) { const error = await response.json(); console.error( "Shorten the profile custom field values before retrying", error, ); } else if (!response.ok) { throw new Error(`Minerva API returned ${response.status}`); } ``` ## Required-field rollout guidance After a definition becomes required, the next profile create or onboarding request must include a valid non-null value. The change does not backfill existing profiles or make a PATCH fail when that required custom field is omitted. Supplied PATCH values still validate against the latest type, archive status, and Choice vocabulary. Before an administrator enables Required: 1. Inventory every profile creation path, including direct create, onboarding, CSV, and XLSX. 2. Update producers to send the immutable key with a correctly typed value. 3. Test missing, `null`, wrong-type, unknown-key, and archived-key requests. 4. Coordinate the activation time with the administrator. 5. Monitor HTTP 400 responses after activation. Prefer a forward edit that makes the field optional again. Historical rollback replays an old snapshot through current validation and can return HTTP 409 if it would omit a saved Choice value; see [Archive, history, and rollback](/profile-custom-fields-guide#archive-history-and-rollback). Optional is the safer default when not every source system has the value. ## Backward compatibility `profileCustomFields` is optional in both requests and responses. Existing clients can continue sending the old profile request shape. Responses omit the array when no stored values resolve to active definitions, preserving the previous response shape. Stored values are retained when a definition is archived. After the read view refreshes, archived definitions and values with no active definition are not emitted. Clients that deserialize with strict schemas should allow the optional array before the feature is enabled. Each array item contains `key`, `label`, `type`, and `value`; `valueLabel` is optional and is used for Choice fields. ## Endpoint reference Use the **Profiles - Endpoints** section of the [API Reference](/api-reference/introduction) for generated schemas and operation details: * Create Profile: `POST /profiles` * Create Profile (Onboarding): `POST /onboarding/profiles` * Update Profile: `PATCH /profiles/{profileId}` * Get Profile Details: `GET /profiles/{profileId}` * List profiles: `GET /profiles` # Profile Groups API Source: https://docs.gominerva.com/api-reference/profile-groups Create and manage workspace-scoped profile groups for dynamic profile segmentation. Use the Profile Groups API to create and maintain the workspace-scoped segment labels that can be assigned to CLM profiles. Profile groups support dynamic customer segmentation, such as risk populations, product lines, or onboarding cohorts, without creating new workspaces. For product concepts, UI workflows, and example segmentation models, see the [Profile Groups Guide](/profile-groups-guide). Profile Groups API calls use application API key authentication. The API key determines the tenant and workspace scope for every request; callers do not pass tenant or workspace IDs in the route. ## Endpoints ```http theme={null} GET https://api.gominerva.com/tenant-config/v1/profile-groups POST https://api.gominerva.com/tenant-config/v1/profile-groups GET https://api.gominerva.com/tenant-config/v1/profile-groups/{profileGroupId} PATCH https://api.gominerva.com/tenant-config/v1/profile-groups/{profileGroupId} DELETE https://api.gominerva.com/tenant-config/v1/profile-groups/{profileGroupId} ``` Authenticate with the same API key header used by the other Minerva API endpoints: ```bash theme={null} x-api-key: YOUR_API_KEY ``` Application API keys are managed from **Administration** > **Developers** in the Minerva dashboard. ## Object Model | Field | Description | | --------------------------- | --------------------------------------------------------------------------- | | `id` | Minerva-generated profile group ID. Use this value in profile assignments. | | `key` | Read-only normalized key generated by Minerva from the initial group label. | | `name` | Customer-facing group label shown in the dashboard. | | `description` | Optional description of the population represented by the group. | | `priority` | Non-negative priority. Higher values win when a profile has many groups. | | `archived` | Whether the group is archived. Archived groups are hidden by default. | | `monitoringFeedFrequencies` | Optional feed cadence overrides for profiles assigned to the group. | Do not supply id or key when creating a profile group. Minerva generates both values. Store and reuse the returned id when assigning profiles to groups. ## Monitoring Frequencies `monitoringFeedFrequencies` can include any of the feed keys below. Omitted feeds inherit the workspace-level monitoring frequency. | Feed | Allowed values | | ----------- | ---------------------------------------------------------------------------------------- | | `Sanctions` | `deltas`, `daily`, `weekly`, `monthly`, `quarterly`, `semiannually`, `annually`, `never` | | `PEP` | `daily`, `weekly`, `monthly`, `quarterly`, `semiannually`, `annually`, `never` | | `News` | `daily`, `weekly`, `monthly`, `quarterly`, `semiannually`, `annually`, `never` | `deltas` is only supported for Sanctions monitoring. ## Create Risk Segments This example creates high, medium, and low risk groups. Higher-risk groups use more frequent monitoring, while lower-risk groups use less frequent monitoring. ```bash cURL theme={null} curl -X POST "https://api.gominerva.com/tenant-config/v1/profile-groups" \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "name": "High Risk", "description": "Enhanced diligence customers requiring the most frequent monitoring.", "priority": 100, "monitoringFeedFrequencies": { "Sanctions": "deltas", "PEP": "weekly", "News": "weekly" } }' ``` ```javascript JavaScript theme={null} const response = await fetch( "https://api.gominerva.com/tenant-config/v1/profile-groups", { method: "POST", headers: { "x-api-key": process.env.MINERVA_API_KEY, "Content-Type": "application/json", }, body: JSON.stringify({ name: "High Risk", description: "Enhanced diligence customers requiring the most frequent monitoring.", priority: 100, monitoringFeedFrequencies: { Sanctions: "deltas", PEP: "weekly", News: "weekly", }, }), }, ); if (!response.ok) { throw new Error(`Minerva API returned ${response.status}`); } const data = await response.json(); const highRiskGroupId = data.result.profileGroup.id; ``` ```python Python theme={null} import os import requests response = requests.post( "https://api.gominerva.com/tenant-config/v1/profile-groups", headers={ "x-api-key": os.environ["MINERVA_API_KEY"], "Content-Type": "application/json", }, json={ "name": "High Risk", "description": "Enhanced diligence customers requiring the most frequent monitoring.", "priority": 100, "monitoringFeedFrequencies": { "Sanctions": "deltas", "PEP": "weekly", "News": "weekly", }, }, timeout=30, ) response.raise_for_status() high_risk_group_id = response.json()["result"]["profileGroup"]["id"] ``` Repeat the create call for medium and low risk populations: ```json theme={null} [ { "name": "Medium Risk", "description": "Standard monitored customers with periodic review.", "priority": 50, "monitoringFeedFrequencies": { "Sanctions": "daily", "PEP": "monthly", "News": "monthly" } }, { "name": "Low Risk", "description": "Lower-risk customers monitored on a reduced cadence.", "priority": 10, "monitoringFeedFrequencies": { "Sanctions": "monthly", "PEP": "quarterly", "News": "quarterly" } } ] ``` ## List Groups ```bash cURL theme={null} curl -G "https://api.gominerva.com/tenant-config/v1/profile-groups" \ -H "x-api-key: YOUR_API_KEY" ``` Archived groups are excluded by default. Include them when reconciling older assignments: ```bash cURL theme={null} curl -G "https://api.gominerva.com/tenant-config/v1/profile-groups" \ -H "x-api-key: YOUR_API_KEY" \ --data-urlencode "includeArchived=true" ``` ## Assign Profiles To Groups Creating a profile group only creates the reusable segment. Assign profiles to one or more groups by setting `profileGroupIds` on the profile create or update request. ```bash cURL theme={null} curl -X PATCH "https://api.gominerva.com/clm/v1/profiles/PROFILE_ID" \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{ "profileGroupIds": [ "665f0d4c2d2f7c2b2f2f2f31", "665f0d4c2d2f7c2b2f2f2f32" ] }' ``` Send an empty array to remove all group assignments from a profile: ```bash cURL theme={null} curl -X PATCH "https://api.gominerva.com/clm/v1/profiles/PROFILE_ID" \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data '{"profileGroupIds": []}' ``` ## Filter Profiles By Group Use the profile list endpoint with `profile_group_ids` to retrieve profiles assigned to any of the provided groups. ```bash cURL theme={null} curl -G "https://api.gominerva.com/clm/v1/profiles" \ -H "x-api-key: YOUR_API_KEY" \ --data-urlencode "profile_group_ids=665f0d4c2d2f7c2b2f2f2f31,665f0d4c2d2f7c2b2f2f2f32" ``` ## Archive A Group `DELETE` archives a profile group; it does not permanently delete it. ```bash cURL theme={null} curl -X DELETE \ "https://api.gominerva.com/tenant-config/v1/profile-groups/665f0d4c2d2f7c2b2f2f2f31" \ -H "x-api-key: YOUR_API_KEY" ``` Archived groups are hidden from active group lists and dashboard selection, but their IDs may still exist on older profile records for audit and reconciliation. # Add Profile Comment Source: https://docs.gominerva.com/api-reference/profile-management/add-profile-comment /api-reference/profiles.json post /profiles/{profileId}/comments Adds a comment to a screening profile. Comments are useful for recording analyst rationale, follow-up notes, and review context alongside the profile record. Supported `kind` values: - `profile`: a general note on the profile. - `match`: a note associated with a potential match. Include `matchId` when available. # Archive Profile Group Source: https://docs.gominerva.com/api-reference/profile-management/archive-profile-group /api-reference/profiles.json delete /profile-groups/{profileGroupId} Archive a profile group. This is a soft delete: existing profile records keep their stored group IDs, but archived groups are excluded from active profile group lists unless requested. # Create Profile Source: https://docs.gominerva.com/api-reference/profile-management/create-profile /api-reference/profiles.json post /profiles The **POST** method on the resource group can be used to create a new profile without performing any initial screening. This method can be helpful for migrations or for synchronizing new profile creation from an admin system to Minerva profiles for the organization. Supply organization-defined values in `profileCustomFields`, keyed by immutable definition key. The request retrieves the latest definitions before validation, so newly required fields, archives, types, and Choice values are enforced. Unknown or archived keys and wrong types return HTTP 400; if definitions cannot be retrieved, the write is rejected. # Create Profile Group Source: https://docs.gominerva.com/api-reference/profile-management/create-profile-group /api-reference/profiles.json post /profile-groups Create a workspace-scoped profile group for dynamic customer segmentation. The API key determines the tenant and workspace; profile group IDs and keys are generated by Minerva. # Create Profile (Onboarding) Source: https://docs.gominerva.com/api-reference/profile-management/create-profile-onboarding /api-reference/profiles.json post /onboarding/profiles The **POST** method on the resource group can be used to create a new profile while performing screening on that profile at the same time. This method allows for the creation of profiles with potential onboarding review tasks and enrollment into ongoing monitoring. Supply organization-defined values in `profileCustomFields`, keyed by immutable definition key. The request retrieves the latest definitions before validation, so newly required fields, archives, types, and Choice values are enforced. Unknown or archived keys and wrong types return HTTP 400; if definitions cannot be retrieved, the write is rejected. # Generate profile audit PDF Source: https://docs.gominerva.com/api-reference/profile-management/generate-profile-audit-pdf /api-reference/profiles.json post /profile-audit-reports/v1/profiles/{profile_id}/pdf Returns a PDF audit export for the specified screening profile. Provide the profile ID in the path and omit the request body. Minerva generates the report from stored records, including profile details, screening history, retained match evidence, analyst comments, and the authenticated application that requested the export. The API key must belong to an application that can access the profile's tenant and workspace. # Get Profile Details Source: https://docs.gominerva.com/api-reference/profile-management/get-profile-details /api-reference/profiles.json get /profiles/{profileId} The **GET** method on a single profile resource returns profile details by ID. When stored custom values resolve to active organization definitions, the response includes an optional `profileCustomFields` array in definition priority order. Definition edits and archives may take up to 60 seconds to appear in the response; stored values do not change. After the read view refreshes, renamed labels are updated and archived fields are omitted. # Get Profile Group Source: https://docs.gominerva.com/api-reference/profile-management/get-profile-group /api-reference/profiles.json get /profile-groups/{profileGroupId} Retrieve one workspace-scoped profile group by its Minerva-generated ID. # List Profile Groups Source: https://docs.gominerva.com/api-reference/profile-management/list-profile-groups /api-reference/profiles.json get /profile-groups List workspace-scoped profile groups available to the application API key. By default, archived groups are excluded. # List profiles Source: https://docs.gominerva.com/api-reference/profile-management/list-profiles /api-reference/profiles.json get /profiles The **GET** method on the resource group lists profiles previously created in the requester's organization. This can be used to extract profiles and sync them to an internal system, or to build integrations that fetch profiles according to selected filters. Each profile can include an optional `profileCustomFields` array when stored values resolve to active organization definitions. Definition edits and archives may take up to 60 seconds to appear in list responses; stored values do not change. After the read view refreshes, renamed labels are updated and archived fields are omitted. Existing profiles with no resolved custom values retain the previous response shape. # Update Profile Source: https://docs.gominerva.com/api-reference/profile-management/update-profile /api-reference/profiles.json patch /profiles/{profileId} The **PATCH** method updates the fields supplied for one profile. In `profileCustomFields`, omitted keys remain unchanged and `null` clears the named value. Required custom fields that are not included in the request are not checked again. Supplied custom fields are validated against the latest definitions, so archives, types, and Choice values are enforced. Unknown or archived keys and values of the wrong type return HTTP 400; if definitions cannot be retrieved, the write is rejected. # Update Profile Group Source: https://docs.gominerva.com/api-reference/profile-management/update-profile-group /api-reference/profiles.json patch /profile-groups/{profileGroupId} Update profile group labels, priority, archived status, or monitoring frequency overrides. The profile group key cannot be supplied or changed through the public API. # Create a canvas Source: https://docs.gominerva.com/api-reference/relationships-canvas/create-a-canvas /api-reference/risk-assessment-agents.json post /assessments/{assessmentId}/canvases Creates a blank or subject-graph canvas for the assessment. # Delete a canvas Source: https://docs.gominerva.com/api-reference/relationships-canvas/delete-a-canvas /api-reference/risk-assessment-agents.json delete /assessments/{assessmentId}/canvases/{canvasId} Deletes a canvas after optimistic version checking. # Get a canvas by id Source: https://docs.gominerva.com/api-reference/relationships-canvas/get-a-canvas-by-id /api-reference/risk-assessment-agents.json get /assessments/{assessmentId}/canvases/{canvasId} Returns a canvas by id after verifying it belongs to the requested assessment and application tenant. # Get or create the default canvas Source: https://docs.gominerva.com/api-reference/relationships-canvas/get-or-create-the-default-canvas /api-reference/risk-assessment-agents.json get /assessments/{assessmentId}/canvas Returns the default assessment canvas, creating one from the subject graph template when none exists. # List assessment canvases Source: https://docs.gominerva.com/api-reference/relationships-canvas/list-assessment-canvases /api-reference/risk-assessment-agents.json get /assessments/{assessmentId}/canvases Lists all canvases attached to the assessment. # Rename a canvas Source: https://docs.gominerva.com/api-reference/relationships-canvas/rename-a-canvas /api-reference/risk-assessment-agents.json patch /assessments/{assessmentId}/canvases/{canvasId} Renames a canvas with optimistic version checking. # Save a canvas by id Source: https://docs.gominerva.com/api-reference/relationships-canvas/save-a-canvas-by-id /api-reference/risk-assessment-agents.json put /assessments/{assessmentId}/canvases/{canvasId} Replaces a canvas state by id with optimistic version checking. # Save the default canvas Source: https://docs.gominerva.com/api-reference/relationships-canvas/save-the-default-canvas /api-reference/risk-assessment-agents.json put /assessments/{assessmentId}/canvas Replaces the default canvas state. Version mismatches return 409 so clients can reload before overwriting another editor's work. # Add an assessment comment Source: https://docs.gominerva.com/api-reference/review-and-collaboration/add-an-assessment-comment /api-reference/risk-assessment-agents.json post /assessments/{assessmentId}/comments Adds a general or object-scoped comment to the assessment audit trail. created_by is derived from the application key. # Answer an agent question Source: https://docs.gominerva.com/api-reference/review-and-collaboration/answer-an-agent-question /api-reference/risk-assessment-agents.json post /assessments/{assessmentId}/questions/{questionId}/answer Answers an open assessment question and lets the run continue once the runtime processes the corresponding command. # Append assessment notes Source: https://docs.gominerva.com/api-reference/review-and-collaboration/append-assessment-notes /api-reference/risk-assessment-agents.json post /assessments/{assessmentId}/notes/append Appends markdown to assessment notes using optimistic concurrency through expected_version. # List assessment comments Source: https://docs.gominerva.com/api-reference/review-and-collaboration/list-assessment-comments /api-reference/risk-assessment-agents.json get /assessments/{assessmentId}/comments Lists assessment, task, CRR, or canvas comments. Query filters can be combined for specific subjects, criteria, canvases, or event kinds. # Replace assessment notes Source: https://docs.gominerva.com/api-reference/review-and-collaboration/replace-assessment-notes /api-reference/risk-assessment-agents.json put /assessments/{assessmentId}/notes Replaces assessment notes using optimistic concurrency through expected_version. # Resolve an agent confirmation Source: https://docs.gominerva.com/api-reference/review-and-collaboration/resolve-an-agent-confirmation /api-reference/risk-assessment-agents.json post /assessments/{assessmentId}/confirmations/{confirmationId}/resolve Resolves a pending confirmation request produced by the agent. # Update task details Source: https://docs.gominerva.com/api-reference/review-and-collaboration/update-task-details /api-reference/risk-assessment-agents.json patch /assessments/{assessmentId}/tasks/{taskId} Updates task context, evidence ids, resolution fields, and optional status. # Update task status Source: https://docs.gominerva.com/api-reference/review-and-collaboration/update-task-status /api-reference/risk-assessment-agents.json patch /assessments/{assessmentId}/tasks/{taskId}/status Manually updates a task status and records a status-update comment. Terminal task statuses require comment_markdown explaining the customer-facing rationale. # Risk Assessment Agents API Source: https://docs.gominerva.com/api-reference/risk-assessment-agents How to create, run, review, and collaborate on beta agent risk assessments through the Minerva API. The Risk Assessment Agents API lets approved applications create and manage beta agent-driven risk assessments programmatically. Beta API: Risk assessment agent endpoints require beta enablement and application access. Contact your Minerva representative or [support@gominerva.com](mailto:support@gominerva.com) before building against these endpoints. ## Base URL Use the central Minerva API domain: ```text theme={null} https://api.gominerva.com/risk-assessments/v2 ``` Your Minerva contact will confirm when this public base URL is enabled for your application and environment. Internally, these endpoints route to Minerva's risk assessment service customer API. ## Authentication Use a Minerva application API key. ```bash theme={null} Authorization: Api-Key YOUR_API_KEY ``` The legacy `X-Api-Key` header is also accepted by the service, but new integrations should use the `Authorization: Api-Key ...` header. The application key determines the tenant, workspace, and actor context. Do not send tenant or workspace identifiers in the request body unless Minerva has explicitly documented a field for that endpoint. For method-level endpoint reference, use Agent Risk Assessments - Endpoints in the API Reference sidebar. ## API Usage Guide The most common integration flow is: 1. fetch available workflows 2. create a draft assessment 3. start the agent run 4. poll the assessment summary until it is ready for review, blocked, or terminal 5. add user input or steering when the agent needs more context 6. read tasks and risks 7. conclude the assessment after reviewer validation Minerva responses use the standard envelope: ```json theme={null} { "status": 200, "msg": "OK", "result": { "assessment": {}, "summary": {}, "tasks": [] } } ``` Read response data from `result.assessment`, `result.summary`, `result.tasks`, and similar result fields. ## Create An Assessment The exact workflow, scorecard, and subject fields available to your application depend on your beta configuration. Fetch workflows and scorecards first, then create an assessment using the selected IDs. ```bash theme={null} curl -sS -X POST \ https://api.gominerva.com/risk-assessments/v2/assessments \ -H "Authorization: Api-Key YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "title": "Northstar Holdings KYB onboarding review", "workflow_id": "workflow_kyb_onboarding", "context": { "purpose": "KYB onboarding", "description": "Review registration, ownership, screening exposure, and adverse media before onboarding." }, "subjects": [ { "type": "organization", "name": "Northstar Holdings Inc.", "registration_id": "123456789", "jurisdiction": { "country": "CA", "state": "ON" } } ] }' ``` The response includes the `assessment_id`. Save it for subsequent lifecycle, upload, run, review, and report steps. ### Create And Start In JavaScript ```javascript theme={null} const API_BASE = "https://api.gominerva.com/risk-assessments/v2"; async function minerva(path, { method = "GET", body } = {}) { const response = await fetch(`${API_BASE}${path}`, { method, headers: { Authorization: `Api-Key ${process.env.MINERVA_API_KEY}`, "Content-Type": "application/json", }, body: body ? JSON.stringify(body) : undefined, }); const payload = await response.json(); if (!response.ok) { throw new Error(payload?.msg || `Minerva API error ${response.status}`); } return payload.result; } const { assessment } = await minerva("/assessments", { method: "POST", body: { title: "Northstar Holdings KYB onboarding review", purpose: "KYB onboarding", workflow_id: "workflow_kyb_onboarding", context: { description: "Review registration, ownership, screening exposure, and adverse media before onboarding.", }, subjects: [ { type: "organization", name: "Northstar Holdings Inc.", locations: [{ type: "headquarters", country: "CA", state: "ON" }], registrations: [ { registration_id: "123456789", registry_name: "Ontario Business Registry", jurisdiction: { level: "state", country: "CA", state: "ON" }, }, ], }, ], }, }); await minerva(`/assessments/${assessment.assessment_id}/start`, { method: "POST", body: { reason: "Start automated KYB review from onboarding case CASE-12345.", }, }); ``` ## Start The Agent Run ```bash theme={null} curl -sS -X POST \ https://api.gominerva.com/risk-assessments/v2/assessments/ASSESSMENT_ID/start \ -H "Authorization: Api-Key YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "reason": "Start automated EDD investigation from case CASE-12345." }' ``` Starting an assessment creates an agent run owned by the risk assessment service. Use the run and trajectory endpoints to inspect progress. ## Poll Status And Completion Use `GET /assessments/{assessmentId}/summary` for polling. It returns compact state, task status counts, client risk rating counts, timestamps, and the latest run reference. ```bash theme={null} curl -sS \ https://api.gominerva.com/risk-assessments/v2/assessments/ASSESSMENT_ID/summary \ -H "Authorization: Api-Key YOUR_API_KEY" \ | jq '.result.summary | { assessment_id, status, task_status_counts, latest_run, updated_at, ready_at, concluded_at }' ``` Interpret assessment status as: | Status | Meaning | Integration behavior | | ------------------ | ------------------------------------------------------------- | --------------------------------------------------------------------------- | | `draft` | Assessment exists but has not started. | Start it when required input is present. | | `running` | The agent is actively working. | Keep polling summary or trajectory. | | `waiting_for_user` | The agent needs human/application input. | Read trajectory, questions, confirmations, or commands, then call `/input`. | | `interrupted` | Work was paused or interrupted. | Inspect trajectory and call `/resume` when ready. | | `ready_for_review` | Agent work is complete and ready for human/API review. | Read tasks, risks, evidence, and CRR before concluding. | | `reopened` | A previously reviewed or terminal assessment needs more work. | Review comments/tasks and resume or add input as needed. | | `concluded` | Final reviewer/API conclusion has been recorded. | Treat as final for downstream systems. | | `cancelled` | Assessment was cancelled. | Stop polling and record cancellation. | | `failed` | Run or assessment failed. | Stop polling, capture context, and contact Minerva if repeatable. | `ready_for_review` means the agent work is complete. It is not the same as a final compliance decision. Use `concluded` only after your reviewer or integration has validated tasks, risks, evidence, and comments. ### Polling Example ```javascript theme={null} const REVIEW_READY = new Set(["ready_for_review"]); const TERMINAL = new Set(["concluded", "cancelled", "failed"]); const ATTENTION_REQUIRED = new Set(["waiting_for_user", "interrupted"]); async function waitForAssessmentReview(assessmentId, options = {}) { const timeoutMs = options.timeoutMs ?? 30 * 60 * 1000; const intervalMs = options.intervalMs ?? 10_000; const startedAt = Date.now(); while (Date.now() - startedAt < timeoutMs) { const { summary } = await minerva(`/assessments/${assessmentId}/summary`); if (REVIEW_READY.has(summary.status) || TERMINAL.has(summary.status)) { return summary; } if (ATTENTION_REQUIRED.has(summary.status)) { return summary; } await new Promise((resolve) => setTimeout(resolve, intervalMs)); } throw new Error(`Timed out waiting for assessment ${assessmentId}`); } ``` Use a polling interval appropriate to your workflow. For most integrations, `10` to `30` seconds is enough. Avoid tight polling loops. ## Track Run Progress Use the trajectory endpoint when you need a detailed activity stream, tool calls, intermediate messages, or evidence of why the agent is waiting. ```bash theme={null} curl -sS \ "https://api.gominerva.com/risk-assessments/v2/assessments/ASSESSMENT_ID/trajectory?after_sequence=0&limit=100&sort_direction=asc" \ -H "Authorization: Api-Key YOUR_API_KEY" ``` For incremental polling, store the highest returned sequence and pass it as `after_sequence` on the next call. ```javascript theme={null} let afterSequence = 0; async function readNewTrajectoryEvents(assessmentId) { const params = new URLSearchParams({ after_sequence: String(afterSequence), limit: "100", sort_direction: "asc", }); const result = await minerva( `/assessments/${assessmentId}/trajectory?${params}`, ); const events = result.trajectory || result.events || []; for (const event of events) { afterSequence = Math.max(afterSequence, event.sequence || 0); } return events; } ``` ## Check Task Completion Use `GET /assessments/{assessmentId}/tasks` to inspect task status, notes, questions, confirmations, and client risk rating state. ```bash theme={null} curl -sS \ https://api.gominerva.com/risk-assessments/v2/assessments/ASSESSMENT_ID/tasks \ -H "Authorization: Api-Key YOUR_API_KEY" \ | jq '.result | { task_status_counts, tasks: [ .tasks[] | { task_id, title, required, status, tags, evidence_ids, risk_ids, completed_at, incomplete_at, requires_review_at } ], questions, confirmations, client_risk_ratings }' ``` Task statuses are: | Status | Meaning | | ----------------- | -------------------------------------------------------- | | `pending` | Task has not started. | | `in_progress` | Task is being worked. | | `complete` | Task is complete according to workflow requirements. | | `incomplete` | Task could not be completed with available evidence. | | `requires_review` | Task has output or risk that needs human/API validation. | Use `task_status_counts` for queue and completion checks, but read individual tasks before concluding. ```javascript theme={null} function taskCompletionSummary(tasks) { const required = tasks.filter((task) => task.required); return { required_count: required.length, complete: required.filter((task) => task.status === "complete").length, requires_review: required.filter( (task) => task.status === "requires_review", ).length, incomplete: required.filter((task) => task.status === "incomplete").length, open: required.filter((task) => ["pending", "in_progress"].includes(task.status), ).length, }; } const { tasks } = await minerva(`/assessments/${assessmentId}/tasks`); const completion = taskCompletionSummary(tasks); ``` To find work needing review across many assessments, use the list endpoint filters: ```bash theme={null} curl -sS \ "https://api.gominerva.com/risk-assessments/v2/assessments?status=ready_for_review,reopened&task_status=requires_review,incomplete&sort_by=updated_at&sort_direction=desc&limit=25" \ -H "Authorization: Api-Key YOUR_API_KEY" ``` ## Get Risks Use `GET /assessments/{assessmentId}` to read the full assessment document. Risk findings are returned on `result.assessment.risks`. ```bash theme={null} curl -sS \ https://api.gominerva.com/risk-assessments/v2/assessments/ASSESSMENT_ID \ -H "Authorization: Api-Key YOUR_API_KEY" \ | jq '.result.assessment.risks // []' ``` Each risk finding can include: | Field | Use | | -------------- | ------------------------------------------------------------------- | | `risk_id` | Stable risk finding identifier. | | `title` | Short risk title. | | `summary` | Human-readable finding summary. | | `severity` | `low`, `medium`, `high`, or `critical`. | | `category` | Broad category such as screening, ownership, adverse media, or CRR. | | `tags` | Workflow-specific topic labels for more precise filtering. | | `status` | `active`, `resolved`, `false_positive`, or `accepted`. | | `subject_ids` | Subjects implicated by the finding. | | `task_ids` | Workflow tasks associated with the finding. | | `evidence_ids` | Evidence supporting the finding. | | `source_urls` | Source URLs supporting the finding, when available. | There is not currently a separate customer endpoint that lists risks independently from the assessment document. Filter risks client-side from the assessment payload. ## Filter Risks By Topic, Tag, Status, Or Severity Risk tags are configured by the workflow and generated during the assessment. Do not assume every tenant uses the same tag vocabulary. Use your workflow's task tags and returned risk tags as the source of truth. Common topic groups might include: | Topic group | Example categories or tags | | -------------------------- | ---------------------------------------------------------------------------- | | Screening | `screening`, `sanctions`, `pep`, `watchlist`, `criminal` | | Adverse media and legal | `adverse_media`, `legal`, `litigation`, `fraud`, `corruption`, `enforcement` | | Ownership and control | `ownership`, `control`, `ubo`, `nominee`, `corporate_structure` | | Geography and jurisdiction | `geography`, `jurisdiction`, `high_risk_jurisdiction` | | Source of funds or wealth | `source_of_funds`, `source_of_wealth`, `sof`, `sow` | | Client risk rating | `crr`, `client_risk_rating`, `risk_rating` | ### Filter With `jq` ```bash theme={null} TOPIC="ownership" curl -sS \ https://api.gominerva.com/risk-assessments/v2/assessments/ASSESSMENT_ID \ -H "Authorization: Api-Key YOUR_API_KEY" \ | jq --arg topic "$TOPIC" ' .result.assessment.risks // [] | map(select((.status // "active") == "active")) | map(select( (.category == $topic) or ((.tags // []) | index($topic)) )) ' ``` To filter by several related tags: ```bash theme={null} curl -sS \ https://api.gominerva.com/risk-assessments/v2/assessments/ASSESSMENT_ID \ -H "Authorization: Api-Key YOUR_API_KEY" \ | jq ' ["sanctions", "pep", "watchlist"] as $topics | .result.assessment.risks // [] | map(select((.status // "active") == "active")) | map(select( (.category as $category | $topics | index($category)) or ((.tags // []) as $tags | any($topics[]; $tags | index(.))) )) ' ``` ### Filter In JavaScript ```javascript theme={null} const severityRank = { low: 1, medium: 2, high: 3, critical: 4, }; function riskMatchesTopic(risk, topics) { const normalizedTopics = new Set(topics.map((topic) => topic.toLowerCase())); const category = String(risk.category || "").toLowerCase(); const tags = (risk.tags || []).map((tag) => String(tag).toLowerCase()); return ( normalizedTopics.has(category) || tags.some((tag) => normalizedTopics.has(tag)) ); } function filterRisks( risks, { topics = [], statuses = ["active"], minSeverity = "low", subjectIds = [], taskIds = [], } = {}, ) { const allowedStatuses = new Set(statuses); const subjectFilter = new Set(subjectIds); const taskFilter = new Set(taskIds); const minRank = severityRank[minSeverity] || severityRank.low; return (risks || []).filter((risk) => { const status = risk.status || "active"; if (!allowedStatuses.has(status)) return false; if ((severityRank[risk.severity] || 0) < minRank) return false; if (topics.length > 0 && !riskMatchesTopic(risk, topics)) return false; if ( subjectFilter.size > 0 && !(risk.subject_ids || []).some((id) => subjectFilter.has(id)) ) { return false; } if ( taskFilter.size > 0 && !(risk.task_ids || []).some((id) => taskFilter.has(id)) ) { return false; } return true; }); } const { assessment } = await minerva(`/assessments/${assessmentId}`); const sanctionsOrPepRisks = filterRisks(assessment.risks, { topics: ["sanctions", "pep", "watchlist"], minSeverity: "medium", }); const ownershipRisks = filterRisks(assessment.risks, { topics: ["ownership", "control", "ubo", "nominee"], statuses: ["active", "accepted"], }); ``` ### Filter Risks By Task Tags Task tags and risk tags should align with your workflow taxonomy. When you want "risks related to tasks tagged ownership," read tasks and risks together: ```javascript theme={null} const [{ assessment }, { tasks }] = await Promise.all([ minerva(`/assessments/${assessmentId}`), minerva(`/assessments/${assessmentId}/tasks`), ]); const ownershipTaskIds = new Set( tasks .filter((task) => (task.tags || []).includes("ownership")) .map((task) => task.task_id), ); const ownershipTaskRiskIds = new Set( tasks .filter((task) => ownershipTaskIds.has(task.task_id)) .flatMap((task) => task.risk_ids || []), ); const risksForOwnershipTasks = (assessment.risks || []).filter((risk) => { return ( ownershipTaskRiskIds.has(risk.risk_id) || (risk.task_ids || []).some((taskId) => ownershipTaskIds.has(taskId)) ); }); ``` ## Provide Steering Use steering when the run should adjust direction without creating a new assessment. ```bash theme={null} curl -sS -X POST \ https://api.gominerva.com/risk-assessments/v2/assessments/ASSESSMENT_ID/steer \ -H "Authorization: Api-Key YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Prioritize official registry evidence before adverse media. Add any parent entities discovered during ownership review as related subjects." }' ``` Good steering is specific, short, and tied to the current assessment. Do not use steering to bypass required review or evidence requirements. Use `/steer` when you want to change how the agent proceeds. Use `/input` when you are answering a question, providing missing facts, or adding more instructions as user-provided context. ```bash theme={null} curl -sS -X POST \ https://api.gominerva.com/risk-assessments/v2/assessments/ASSESSMENT_ID/input \ -H "Authorization: Api-Key YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Additional instruction from the onboarding case: treat the newly uploaded ownership chart as the customer-supplied version, but corroborate beneficial owners against official registry or reliable public sources before marking the ownership task complete.", "reason": "Customer supplied a revised ownership chart after the run started." }' ``` Both `/steer` and `/input` accept: | Field | Use | | --------------- | ------------------------------------------------------------------ | | `prompt` | Plain-text instruction or answer. | | `message` | Alternate plain-text instruction field. `prompt` is preferred. | | `reason` | Short audit reason for the command. | | `payload` | Structured JSON context for integration-specific instructions. | | `artifact_refs` | References to artifacts already known to the runtime, when needed. | | `run_id` | Optional explicit run id when using the latest-run endpoint. | ## Update Task Status ```bash theme={null} curl -sS -X PATCH \ https://api.gominerva.com/risk-assessments/v2/assessments/ASSESSMENT_ID/tasks/TASK_ID/status \ -H "Authorization: Api-Key YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "status": "requires_review", "comment_markdown": "Ownership task needs analyst review because the registry extract and ownership chart disagree." }' ``` Use status changes to reflect actual review state. Include comments when the reason will matter for audit or handoff. ## Add A Comment ```bash theme={null} curl -sS -X POST \ https://api.gominerva.com/risk-assessments/v2/assessments/ASSESSMENT_ID/comments \ -H "Authorization: Api-Key YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "subject_kind": "assessment", "subject_id": "ASSESSMENT_ID", "markdown": "Please confirm whether the uploaded ownership chart is the current signed version before concluding." }' ``` Comments should name the review question, the evidence or task involved, and the action needed. ## Conclude An Assessment ```bash theme={null} curl -sS -X POST \ https://api.gominerva.com/risk-assessments/v2/assessments/ASSESSMENT_ID/conclude \ -H "Authorization: Api-Key YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "decision": "approved_with_conditions", "summary": "KYB review is complete. Ownership is understood, sanctions/PEP screening did not identify confirmed matches, and the remaining medium-risk ownership factor is documented in the CRR scorecard." }' ``` Conclude only after required tasks, evidence, risk findings, comments, and client risk rating criteria have been reviewed according to your policy. ## Operational Guidance * Create separate application keys for test and Live use. * Confirm beta enablement before using the public route. * Fetch workflows and scorecards instead of hard-coding IDs where possible. * Store assessment IDs in your internal case system. * Use descriptive assessment titles so dashboard users can identify API-created cases. * Upload or register source documents before starting the run when they are material to the task. * Review trajectory and evidence IDs before concluding assessments. * Retry idempotent reads safely, but avoid repeated start or conclude calls without checking current status. * Contact Minerva if the same endpoint returns repeated failures for one tenant, workspace, or workflow. ## Related Guides * [Agent Risk Assessments Guide](/agent-risk-assessments-guide) * [API Introduction](/api-reference/introduction) * [API Keys](/api-reference/api-keys) # Screening Integration Guide Source: https://docs.gominerva.com/api-reference/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? 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 ```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[] └── aliases[] ``` 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`. | Each `match_score` describes the one value it sits on. It compares the search criteria with that value, not with the candidate record as a whole. `hits_info[].aliases[]` repeats the candidate's alternate names with the same three fields, and each entry scores against the search criteria on its own, so scores in one array normally differ. An alias that does not resemble the submitted name reads `0.0` and `none` there, where every entry previously repeated the strongest alias score. 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.`. 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..criteria_match_level` | Summary for one field supplied in the search. | | `.criteria_match_level` | Search input compared with the resolved consensus field value. | | `.sources[n].criteria_match_level` | Search input compared with one source observation. | | `aliases[n].criteria_match_level` | Search input compared with that one alias name. | | `checklist.hits_info[n]..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. ### Alias Scores And The Matched Name `results[i].aliases[]` uses the same name object as `results[i].name`, so each alias carries its own `match_score` and `criteria_match_level`, and scores in one array normally differ. Each pair describes how closely that one alias matched the search criteria. It is not the candidate's overall match strength. A record can hold one `exact` alias beside several `none` aliases, and that is the expected shape: most alternate spellings, former names, and non-Latin variants on a record will not resemble the name that was submitted. `matched_query` marks the highest-scoring alias on the record, and only when that alias also scored above the candidate's primary name. It is present and set to `true` on at most one alias, and it is omitted everywhere else. An alias that scores above the primary name but below another alias does not carry it. Its absence means no alias scored above the primary name. Use it to show a reviewer which name on the record matched the search most closely. Sanctions and PEP records are published under a primary name, so a subject screened under an alias can look unrelated to the search when only that primary name is displayed. Showing the `matched_query` alias next to the primary name explains the hit before the reviewer discounts a real match. In the following abbreviated candidate, the submitted name was `Muammar Gaddafi`. The record is published under `Muammar Qadhafi`. Three aliases score above that primary name, and only the closest one carries `matched_query`. ```json theme={null} { "name": { "value": "Muammar Qadhafi", "match_score": 0.9075, "criteria_match_level": "close" }, "aliases": [ { "value": "Muammar Gaddafi", "match_score": 1.0, "criteria_match_level": "exact", "matched_query": true }, { "value": "Mu'ammar Gaddafi", "match_score": 0.9891, "criteria_match_level": "exact" }, { "value": "Muammar Gadhafi", "match_score": 0.9383, "criteria_match_level": "close" }, { "value": "Muammar Al-Qadhafi", "match_score": 0.8333, "criteria_match_level": "loose" }, { "value": "Muammar Elkaddafi", "match_score": 0.6534, "criteria_match_level": "none" } ] } ``` An alias that does not resemble the search criteria scores low, down to `0.0` and `none`. Entries in `aliases[]` previously repeated the strongest score in the array, so a non-matching name that used to read `exact` now reads `none`. An integration that treats one alias score as the candidate's overall match strength will therefore report lower values than before. Overall match strength is `results[i].score` and `results[i].match_score_info`, and the per-name values in `aliases[]` do not feed either one. `match_score_info.aliases` is a separate summary: it reports the strongest alias evidence used for ranking, and it is not recalculated from the values in `aliases[]`. ## 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. | | `is_best_match` | Present and `true` on the source that supplied the displayed consensus value. It ranks sources against each other, not against the search criteria. | 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. Each entry carries its own closeness scores, and `matched_query` marks the closest-matching alias when it also scored above the primary name. | | `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. ## Automatic Disposition Annotations (New) Workspaces with [Automatic Disposition](/automatic-disposition-guide) 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](/api-reference/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: ```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=" \ --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=" \ --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=" \ --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) * [Automatic Disposition Guide](/api-reference/automatic-disposition-guide) * [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) # Create screening webhook Source: https://docs.gominerva.com/api-reference/screening-webhooks/create-screening-webhook /api-reference/admin-api.json post /v2/webhooks/screening The **POST** method on the resource group can be used to create a new screening webhook. This will automatically generate a webhook key and unique ID for the new webhook. The response payload will contain both the unique ID and the newly generated webhook key which should be stored in a vault or secrets manager for the receiving service to authenticate the request via the "x-webhook-key" header. The webhook key will also be present on any GET requests for the webhooks so it is possible to retrieve the webhook key again in the future. Screening webhooks currently support profile status update events for Screening Workflow Profiles. **Notice:** each tenant is allowed a maximum of 10 webhooks by default. More webhooks are available for enterprise customers upon request. If the maximum for the tenant has been reached, consider reviewing the existing webhooks and deleting un-used webhooks using the **Delete Screening Webhook** method. # Delete screening webhook Source: https://docs.gominerva.com/api-reference/screening-webhooks/delete-screening-webhook /api-reference/admin-api.json delete /v2/webhooks/screening/{webhookId} The **DELETE** method on a single screening webhook resource will delete the webhook with that ID permanently. This will deactivate the webhook and remove it from the list of subscribed webhooks in the tenant and the target server/url will no longer receive notifications from the webhook. This method can be used to deactivate or delete webhooks that are not being used anymore. It may also be necessary to use this endpoint if the maximum number of allowed webhooks for the tenant is reached (default maximum of 10). # Get screening webhook Source: https://docs.gominerva.com/api-reference/screening-webhooks/get-screening-webhook /api-reference/admin-api.json get /v2/webhooks/screening/{webhookId} The **GET** method on a single screening webhook resource will return the details for a single screening webhook by its ID. # List screening webhooks Source: https://docs.gominerva.com/api-reference/screening-webhooks/list-screening-webhooks /api-reference/admin-api.json get /v2/webhooks/screening The **GET** method on the resource group will list screening webhooks that have been previously created in the tenant of the requester. This can be used to extract a list of screening webhooks to review the current webhooks that are in place for the tenant for reference or cleanup purposes. # Test screening webhook Source: https://docs.gominerva.com/api-reference/screening-webhooks/test-screening-webhook /api-reference/admin-api.json post /v2/webhooks/screening/{webhookId}/test The **POST** method on the screening webhook test path will trigger a simulated payload to the destination URL with the webhook key in the "x-webhook-key" header. The header and payload will have the same structure as the payload in production, so it is possible to use the webhook test endpoint during development to test the service logic handling for the configured webhooks. The best use case for this test endpoint and method is to ensure that the destination server and path are properly configured and that the webhook key can be received and authenticated properly. **Notice:** the provided fields will be echoed through as-is, so no conditional simulation is being applied on the test endpoint at this time to check that the values in the fields appropriately match the configured conditions to trigger the webhook. Therefore, it is necessary to provide the desired fields in the webhook test input to trigger the logic configured in your service implementation appropriately. # Update screening webhook Source: https://docs.gominerva.com/api-reference/screening-webhooks/update-screening-webhook /api-reference/admin-api.json patch /v2/webhooks/screening/{webhookId} The **PATCH** method on a single screening webhook resource will update fields on that screening webhook. # Search History Source: https://docs.gominerva.com/api-reference/search-history Retrieve historical Minerva screening requests for audit and reconciliation workflows. Use the search history endpoint to retrieve screening/search request metadata that was created in Minerva for your tenant. This endpoint is intended for audit-purpose search history retrieval: it helps compliance teams reconcile which screenings were run, when they were run, who ran them when that user context is available, and which submitted entities and feeds were included. Search history retrieval is read-only. It does not submit a new screening, change review status, or modify historical records. ## Endpoint ```http theme={null} GET https://api.gominerva.com/v2/search/requests ``` Authenticate with the same API key header used by the other Minerva API endpoints: ```bash theme={null} x-api-key: YOUR_API_KEY ``` The API key determines the tenant whose historical requests are returned. API keys are managed from **Administration** > **Developers** in the Minerva dashboard. ## Query Parameters | Parameter | Description | | ----------------- | ------------------------------------------------------------------------------- | | `page` | One-based page number. Defaults to `1`. | | `limit` | Number of requests to return per page. Defaults to `10` and is capped at `250`. | | `q` | Optional case-insensitive search against submitted entity names. | | `job_id` | Optional search job identifier to retrieve requests from a specific job. | | `created_at_from` | Inclusive lower bound for the request creation time. | | `created_at_to` | Inclusive upper bound for the request creation time. | | `sort_key` | Sort field. Only `created_at` is currently supported. | | `sort` | Sort direction: `desc` or `asc`. Defaults to `desc`. | Use RFC3339 date-time values with an explicit timezone, such as 2026-05-01T00:00:00Z. When building URLs, use your HTTP client's query parameter encoder, URLSearchParams, or --data-urlencode so reserved characters such as : and + are encoded safely. ## List Recent Search Requests ```bash cURL theme={null} curl -G "https://api.gominerva.com/v2/search/requests" \ -H "x-api-key: YOUR_API_KEY" \ --data-urlencode "limit=25" \ --data-urlencode "sort=desc" ``` ```javascript JavaScript theme={null} const params = new URLSearchParams({ limit: "25", sort: "desc", }); const response = await fetch( `https://api.gominerva.com/v2/search/requests?${params}`, { headers: { "x-api-key": process.env.MINERVA_API_KEY, }, }, ); if (!response.ok) { throw new Error(`Minerva API returned ${response.status}`); } const data = await response.json(); ``` ```python Python theme={null} import os import requests response = requests.get( "https://api.gominerva.com/v2/search/requests", headers={"x-api-key": os.environ["MINERVA_API_KEY"]}, params={"limit": 25, "sort": "desc"}, timeout=30, ) response.raise_for_status() data = response.json() ``` ## Retrieve A Date Range Date range filters are inclusive and apply to the request's `created_at` timestamp. ```bash cURL theme={null} curl -G "https://api.gominerva.com/v2/search/requests" \ -H "x-api-key: YOUR_API_KEY" \ --data-urlencode "created_at_from=2026-05-01T00:00:00Z" \ --data-urlencode "created_at_to=2026-05-31T23:59:59Z" \ --data-urlencode "limit=100" \ --data-urlencode "sort=asc" ``` ```javascript JavaScript theme={null} const params = new URLSearchParams({ created_at_from: "2026-05-01T00:00:00Z", created_at_to: "2026-05-31T23:59:59Z", limit: "100", sort: "asc", }); const response = await fetch( `https://api.gominerva.com/v2/search/requests?${params}`, { headers: { "x-api-key": process.env.MINERVA_API_KEY, }, }, ); if (!response.ok) { throw new Error(`Minerva API returned ${response.status}`); } const data = await response.json(); ``` ```python Python theme={null} import os import requests response = requests.get( "https://api.gominerva.com/v2/search/requests", headers={"x-api-key": os.environ["MINERVA_API_KEY"]}, params={ "created_at_from": "2026-05-01T00:00:00Z", "created_at_to": "2026-05-31T23:59:59Z", "limit": 100, "sort": "asc", }, timeout=30, ) response.raise_for_status() data = response.json() ``` ## Example Response ```json theme={null} { "pagination": { "page": 1, "limit": 2, "total_count": 42, "total_pages": 21, "has_next": true, "has_prev": false }, "requests": [ { "id": "665f0d4c2d2f7c2b2f2f2f2f", "legacy_search_id": "legacy-search-123", "tenant_id": "org_123", "config": { "feeds": ["Sanctions", "PEP"] }, "entities": [ { "type": "individual", "name": "Jane Doe", "feeds": ["Sanctions", "PEP"], "custom_id": "case-1001" } ], "created_at": "2026-05-14T13:22:45Z", "updated_at": "2026-05-14T13:22:48Z", "user_id": "user_123", "user_name": "Compliance Analyst", "user_email": "analyst@example.com", "job_id": "665f0d4c2d2f7c2b2f2f2f30" } ] } ``` ## Paginating An Audit Export For a full audit export, request pages until `pagination.has_next` is `false`. Keep the same filters on each page so the result set remains consistent. ```javascript JavaScript theme={null} let page = 1; let hasNext = true; const allRequests = []; while (hasNext) { const params = new URLSearchParams({ created_at_from: "2026-05-01T00:00:00Z", created_at_to: "2026-05-31T23:59:59Z", limit: "250", page: String(page), }); const response = await fetch( `https://api.gominerva.com/v2/search/requests?${params}`, { headers: { "x-api-key": process.env.MINERVA_API_KEY } }, ); if (!response.ok) { throw new Error(`Minerva API returned ${response.status}`); } const data = await response.json(); allRequests.push(...data.requests); hasNext = data.pagination.has_next; page += 1; } ``` ## Retrieving Associated Results The search history response gives you the request metadata and the request identifier. When you need the stored match-level results for a historical request, use the returned id as the request\_id on the search matches endpoint. ```bash cURL theme={null} curl -G "https://api.gominerva.com/v2/search/matches" \ -H "x-api-key: YOUR_API_KEY" \ --data-urlencode "request_id=665f0d4c2d2f7c2b2f2f2f2f" \ --data-urlencode "limit=100" ``` # Batch Asynchronous Search API Source: https://docs.gominerva.com/api-reference/search/batch-asynchronous-search-api /api-reference/core.json post /v1/search **"I want to submit a batch of multiple searches at once to Minerva in an asynchronous way so that I can query the long running job later."** **"I want to submit large volumes of searches at once and query the results overnight to update my systems."** The search endpoint submits a search job and returns a job id which should be used to check on the status of the search. The search is performed in real-time and queries a combination of Minerva internal data as well as open web data. **Performance:** The average completion time of a Minerva search varies based on the feeds requested. A full EDD search, which includes all Minerva feeds, usually completes within 45 seconds. For Sanctions and PEP searches, the search time is often in the 300 millisecond to 3 second range. **Matching Algorithm:** All parameters are matched softly against the database, using the Minerva scoring algorithm. This means that searches for "Male" gender will not necessarily exclude "Female" results if other criteria match strongly enough to the requested parameters. The same is true for geography parameters, where results from nearby cities/states may be returned if enough other criteria match strongly. **Note:** This is the batch asynchronous search API endpoint, which is best used for longer running jobs that include lists of multiple searches at once. Obtaining the search results from this endpoint requires storing the job id to query later, or to poll until completion. If your intent is to submit a search for a single profile at a time and obtain the results for those searches immediately, then it would be better to apply the synchronous search API. **New:** potential matches in this job's completed rows can include Automatic Disposition annotations - see the Batch Search Results response fields and the [Automatic Disposition Guide](/api-reference/automatic-disposition-guide). ## Adverse media risk categories configuration {#adverse-media-risk-categories-configuration} When `News` is included in `feeds`, use `requests[].global_filters.adverse_media_risk_categories` to replace the workspace's Direct API category set for an individual entity in the batch. Each request object may use a different set. Send raw category keys from the request schema; an empty array disables every category for that entity. Omit the field to use workspace configuration. See [Adverse Media Categories](/adverse-media-categories) for category definitions, defaults, and precedence. # Batch Search Results API Source: https://docs.gominerva.com/api-reference/search/batch-search-results-api /api-reference/core.json get /v1/search/{jobid} I submitted an asynchronous search request and got a job ID. Now I want to check the job status and get the results of the batch if the screening is done. On successful submission of a response to the search endpoint, a job id will be returned. Use this job id to query the status of your search. If the search is in progress, it will return progress data indicating how far along the job is to completion. If the search is complete, then the full response object will be returned with the call. For every object in the requests object of the body that was submitted to /search, there will be a response profile object returned by this endpoint. Check out the Profile Data Schema for a detailed view of the profile object. **New:** matches in completed rows can include Automatic Disposition annotations - see the `review_status`, `automatic_disposition`, and `disposition_hint` response fields below and the [Automatic Disposition Guide](/api-reference/automatic-disposition-guide). # Generate PDF Report Source: https://docs.gominerva.com/api-reference/search/generate-pdf-report /api-reference/core.json post /v1/reports Generate PDF reports as evidence that screening in Minerva was completed. The recommended workflow is to pass a single `searchResultId` from a previous `POST /v1/search-sync` response or from a batch result returned by `POST /v1/searchStatus` or `GET /v1/search/{jobid}`. For batch results, use the entity-scoped `searchId` value returned in each result row, such as `_0`. Legacy `results` and `id` payloads are still supported for older integrations. # List historical search requests Source: https://docs.gominerva.com/api-reference/search/list-historical-search-requests /api-reference/core.json get /v2/search/requests Returns paginated historical screening/search request metadata for the authenticated tenant. Use this endpoint for audit-purpose search history retrieval when reconciling screenings that were run in Minerva. # Single Search Synchronous API Source: https://docs.gominerva.com/api-reference/search/single-search-synchronous-api /api-reference/core.json post /v1/search-sync Canonical synchronous single search via request body for single individual or entity screening. Use this POST method for new integrations and whenever supplying combinations of PII such as name, address, date of birth, or personal ID fields for security reasons. Average completion time varies - full EDD search completes within 45 seconds, Sanctions and PEP searches typically complete in 300ms-3 seconds. All parameters are matched softly using the Minerva scoring algorithm. **New:** matches in this response can include Automatic Disposition annotations - see the `review_status`, `automatic_disposition`, and `disposition_hint` response fields below and the [Automatic Disposition Guide](/api-reference/automatic-disposition-guide). ## Adverse media risk categories configuration {#adverse-media-risk-categories-configuration} When `News` is included in `feeds`, use `global_filters.adverse_media_risk_categories` to replace the workspace's Direct API category set for this search. Send raw category keys from the request schema. The override may narrow or widen the workspace set, and an empty array disables every category for this call. Omit the field to use workspace configuration. See [Adverse Media Categories](/adverse-media-categories) for category definitions, defaults, and precedence. # SAML SSO and SCIM Guide Source: https://docs.gominerva.com/authentication-sso-scim-guide How tenant admins configure SAML single sign-on, sign-in modes, and SCIM provisioning in Minerva. SAML single sign-on lets users authenticate through your identity provider before entering Minerva. SCIM provisioning lets your identity provider create, update, and deactivate Minerva tenant users. **Access:** Requires the **Admin** role or above. In the sidebar, go to **Administration** > **Configuration**, then open **Authentication** under **Access and authentication**. Use this guide when you need to: * configure a SAML identity provider for Minerva * choose whether users can sign in with passwords, SSO, or both * configure SCIM user provisioning from an identity provider * rotate SAML signing certificates or SCIM bearer tokens * set up common identity providers such as Okta, Microsoft Entra ID, PingFederate or PingOne, Rippling, and OneLogin SAML and SCIM solve different parts of identity management. SAML controls sign-in. SCIM controls user lifecycle events such as user creation, profile updates, and deactivation. Keep at least one Admin able to sign in while you test SSO. Do not switch to **SSO only** until the SAML test succeeds for an assigned admin user. Minerva SAML sign-in must be service-provider initiated. Users must start SSO either from the tenant-specific **SSO launch URL** shown in Minerva or by opening the Minerva app, entering their email, and selecting **Log in with SSO**. Do not configure IdP app tiles, shortcuts, or bookmarks to post directly to the SAML ACS URL. ## Authentication Settings Page The Authentication page contains four sections: * **Service provider**: Minerva values that you copy into the identity provider, including the SSO launch URL for app tiles * **SAML identity provider**: identity-provider metadata, certificate status, save, and test controls * **SCIM provisioning**: SCIM base URL, bearer token, default role, role mappings, and provisioning controls * **Sign-in mode**: password-only, password plus SSO, or SSO-only access ## Minerva Production Values Use these Minerva production values when configuring your production identity provider app. | Value | Production setting | | ------------------------------- | ----------------------------------------------------------------------------------------------------- | | SAML Entity ID | [https://sso.gominerva.com](https://sso.gominerva.com) | | SAML ACS URL | [https://sso.gominerva.com/\_\_/auth/handler](https://sso.gominerva.com/__/auth/handler) | | SSO launch URL | Tenant-specific value shown in Minerva | | SCIM base URL | [https://scim.gominerva.com/v2](https://scim.gominerva.com/v2) | Lower-environment test tenants may show different values. Always copy the values shown in the Minerva Authentication page for the tenant you are configuring. ## Before You Begin Confirm these items before changing authentication settings: * you have Admin access in Minerva * you have admin access in the identity provider * the users who need Minerva access have email addresses that match their Minerva user emails * you know which IdP group, role, or entitlement values should map to Minerva Admin, Developer, or Member roles * you have a pilot user or group ready for testing Start with **Password + SSO** during rollout. Move to **SSO only** only after the IdP assignment, SAML test, and SCIM pilot all work as expected. ## SAML SSO Setup SAML setup is a two-way exchange: 1. Copy Minerva service-provider values into the identity provider. 2. Copy identity-provider metadata or manual IdP values back into Minerva. 3. Save the SAML provider in Minerva. 4. Test SSO from Minerva with an assigned admin user. 5. Choose the tenant sign-in mode. ### Minerva Values To Copy Into The IdP * **Entity ID** identifies Minerva as the SAML service provider. * **ACS URL** is where the IdP sends the signed SAML response. * **SSO launch URL** is the URL to use for IdP app tiles, bookmarks, or application launch links. * Keep these values unchanged after go-live unless Minerva support directs a rotation. The SSO launch URL and ACS URL are not interchangeable. The launch URL starts SAML from Minerva so browser state is initialized before the IdP handshake. The ACS URL receives the signed SAML response after that handshake. Configure every IdP tile, portal shortcut, browser bookmark, and internal launch link to open the Minerva **SSO launch URL**. Users can also start SSO from the Minerva login page by entering their email and selecting **Log in with SSO**. IdP-initiated SAML flows that send users directly to the ACS URL are not supported and can fail because the required Minerva browser session state has not been created. ### IdP Values To Save In Minerva * **IdP entity ID**, sometimes called issuer * **SSO URL**, sometimes called login URL or SAML endpoint * One or more **X.509 signing certificates** from IdP metadata or certificate export ### Recommended SAML Setup Sequence 1. Open **Administration** > **Configuration** > **Authentication** in Minerva. 2. Copy the Entity ID, ACS URL, and SSO launch URL from the Service provider section. 3. Create a SAML application in the identity provider and paste those Minerva values into the service-provider fields. 4. Set the IdP app tile, start URL, or launch URL to the Minerva SSO launch URL. 5. Set the SAML subject or NameID to the email address users will use in Minerva. 6. Download IdP metadata, or copy the IdP entity ID, SSO URL, and signing certificate. 7. Paste the metadata into Minerva and parse it, or enter the IdP values manually. 8. Save the SAML provider, assign a test admin user in the IdP, and run **Test SSO** in Minerva. 9. After a successful test, choose **Password + SSO** for rollout or **SSO only** when password sign-in should be blocked. ### SAML Field Labels You May See Different IdPs use different labels for the same SAML values. | Minerva field | Common IdP labels | | ---------------------------------- | ---------------------------------------------------------------------------------- | | Entity ID | Audience URI, SP Entity ID, Identifier, Application Entity ID, Relying Party ID | | ACS URL | Assertion Consumer Service URL, Reply URL, Recipient URL, SSO callback, ACS URL | | SSO launch URL | App tile URL, Login URL, Start URL, Initiate login URI, Bookmark URL | | Provider name | Customer-facing app name, provider display name, app name | | IdP entity ID | Issuer, Identity Provider Entity ID, federation metadata entity ID | | SSO URL | Login URL, SAML 2.0 endpoint, Single Sign-On Service URL, IdP SSO URL | | X.509 certificate | Signing certificate, SAML certificate, public certificate, certificate in metadata | ### Sign-In Modes | Mode | What users can do | When to use it | | ------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------- | | Password only | Users sign in with Minerva email and password. | Before SAML is configured, or if SSO is not required. | | Password + SSO | Users can choose password sign-in or SSO. | During rollout, pilot testing, and fallback periods. | | SSO only | Users must sign in through the identity provider. | After SAML has been saved, tested, and assigned to the right users. | ### Certificate Security And Rotation Saved IdP signing certificate contents are hidden after upload. Minerva shows certificate metadata such as expiration date and SHA-256 fingerprint so admins can confirm the active certificate without exposing raw certificate material. When rotating a certificate: 1. Add or rotate the signing certificate in the identity provider. 2. Export fresh IdP metadata, or copy the replacement PEM certificate. 3. Paste the fresh metadata or replacement certificate into Minerva. 4. Save the SAML provider. 5. Run **Test SSO** before the old certificate expires. A certificate mismatch can prevent SSO sign-in. Complete certificate rotation before the old certificate expires, and keep password fallback available until the test succeeds. ## SCIM Provisioning Setup SCIM provisioning uses a Minerva SCIM base URL and bearer token. Generate the token in Minerva, store it in the identity provider, and test the connection before enabling broad provisioning. SCIM does not replace SSO. SAML controls sign-in; SCIM controls the user lifecycle. Configure and test both before moving a tenant to **SSO only**. ### Recommended SCIM Setup Sequence 1. Open **Administration** > **Configuration** > **Authentication** in Minerva. 2. Copy the SCIM base URL from the SCIM provisioning section. 3. Generate a bearer token and store it in the IdP immediately. The full token is shown only once. 4. Create or open the SCIM provisioning connection in the IdP. 5. Paste the SCIM base URL and bearer token into the IdP, then test the connection. 6. Assign a small pilot group and confirm users are created or updated in Minerva. 7. Configure role mappings when IdP groups, roles, or entitlements should control Minerva Admin, Developer, or Member access. 8. Enable SCIM provisioning in Minerva after the IdP connection and pilot assignment are working. ### SCIM Field Labels You May See | Minerva field | Common IdP labels | | ------------------------------------------------------ | ------------------------------------------------------------------- | | SCIM base URL | Tenant URL, Base URL, SCIM endpoint, SCIM connector URL | | Bearer token | Secret token, API token, OAuth bearer token, authorization token | | Default role | Fallback role for users who do not match a role mapping rule | | Role mapping rules | Group Push values, app role values, entitlement values, group names | | Disable dashboard-managed invitations | Use when the IdP should manage user creation and deactivation | ### Provisioning Behavior To Review The IdP should manage: * users created through app assignment * name, email, active status, and mapped role updates * deactivation or suspension when users are removed from scope Before broad rollout, confirm: * whether SCIM should disable dashboard-managed invitations * whether unmatched users should default to Member or a more restrictive role * whether group names or app roles are stable enough to use as Minerva role mapping values ### Role Mapping Minerva supports these tenant roles for provisioned users: | Minerva role | Use for | | -------------------------- | ------------------------------------------------------------------------------------------------------- | | Admin | Users who manage tenant settings, identity configuration, teams, and operational controls. | | Developer | Users who manage API keys, webhooks, and integration delivery tasks without full tenant administration. | | Member | Standard users who use Minerva workflows but do not administer tenant configuration. | Role mapping rules compare the group, role, or entitlement value sent by the IdP with the values configured in Minerva. Keep those values stable and easy to understand, such as **Minerva Admins** or **Minerva Developers**. If no role mapping matches a provisioned user, Minerva applies the configured default role. ## IdP Quick Guides The same Minerva values work across major identity providers, but each IdP uses different labels and connector templates. Use the quick guide below with your IdP administrator. Configure SAML first, then SCIM. Keep at least one Admin able to sign in before changing the tenant to **SSO only**. ### Okta For SAML: 1. Create or open the Minerva SAML app integration in Applications. 2. Set Single sign-on URL and Recipient URL to the Minerva ACS URL. 3. Set Audience URI / SP Entity ID to the Minerva Entity ID. 4. Set Application visibility or the app tile launch URL to the Minerva SSO launch URL. 5. Use the user email address as the Name ID and assign a test admin user. 6. Copy the Identity Provider metadata into Minerva or download the certificate and enter the IdP issuer and SSO URL manually. For SCIM: 1. Enable SCIM provisioning for the same app integration when available. 2. Set the SCIM connector base URL to the Minerva SCIM base URL. 3. Use HTTP Header or bearer-token authentication and paste the Minerva bearer token. 4. Enable create, update, and deactivate user actions. 5. Use Group Push or profile attributes when you want Okta values to drive Minerva role mappings. Notes: * If the Provisioning tab is not available, your Okta org or app template may need SCIM enabled by Okta. * Test with a small assigned group before moving the app to SSO only. ### Microsoft Entra ID For SAML: 1. Create or open an Enterprise Application, then choose Single sign-on > SAML. 2. Set Identifier (Entity ID) to the Minerva Entity ID. 3. Set Reply URL (Assertion Consumer Service URL) to the Minerva ACS URL. 4. Set the application's user access URL or homepage URL to the Minerva SSO launch URL when showing a user-facing app tile. 5. Use user.mail or user.userprincipalname as the user identifier, depending on the email users use in Minerva. 6. Copy the App Federation Metadata URL or download the SAML certificate and enter the issuer, login URL, and certificate in Minerva. For SCIM: 1. Open Provisioning for the Enterprise Application and choose automatic provisioning. 2. Set Tenant URL to the Minerva SCIM base URL. 3. Set Secret Token to the Minerva bearer token and test the connection. 4. Scope provisioning to assigned users and groups unless your rollout plan says otherwise. 5. Map Entra groups or app roles to the values configured in Minerva role mapping rules. Notes: * Entra provisioning runs on a cycle, so successful changes may not appear instantly. * Keep the same Enterprise Application for SAML and provisioning when your tenant policy allows it. ### PingFederate or PingOne For SAML: 1. Create a SAML application or SP connection for Minerva. 2. Set the partner or relying-party entity ID to the Minerva Entity ID. 3. Set the ACS endpoint to the Minerva ACS URL and use an email NameID format. 4. Set the application tile, target URL, or default launch URL to the Minerva SSO launch URL. 5. Export the IdP metadata or record the issuer, SSO endpoint, and active signing certificate. 6. Upload metadata in Minerva or enter the IdP values manually, then save and test. For SCIM: 1. Create an outbound SCIM connection for Minerva when your Ping deployment includes provisioning. 2. Set the SCIM endpoint/base URL to the Minerva SCIM base URL. 3. Use bearer-token authentication with the Minerva SCIM token. 4. Map user email, given name, family name, and active status. 5. Send group, role, or entitlement values when you want Minerva role mappings to apply. Notes: * PingFederate deployments vary by adapter and provisioning connector. Use your IdP administrator to confirm the available SCIM connector. * Export fresh metadata after signing-certificate rotation and update Minerva before the old certificate expires. ### Rippling For SAML: 1. Create a custom SAML or SAML and SCIM app for Minerva in Rippling. 2. Set the ACS or Reply URL to the Minerva ACS URL. 3. Set the SP Entity ID or Audience to the Minerva Entity ID. 4. Set the app launch URL to the Minerva SSO launch URL. 5. Use employee email as the SAML subject and assign a pilot group. 6. Copy Rippling IdP metadata into Minerva or enter the SSO URL, issuer, and signing certificate manually. For SCIM: 1. Enable provisioning on the custom app when your Rippling plan supports SCIM. 2. Set the SCIM URL to the Minerva SCIM base URL. 3. Use the generated Minerva bearer token as the SCIM authentication token. 4. Choose the Rippling employee attributes or groups that should control app assignment. 5. Send group or role values that match the Minerva role mapping rules. Notes: * Rippling is often driven by employee lifecycle rules. Confirm who should be assigned before enabling broad provisioning. * If SCIM is not available in your Rippling app setup, keep user creation in Minerva until your IdP administrator enables it. ### OneLogin For SAML: 1. Use a SAML custom connector or a SCIM Provisioner with SAML connector for Minerva. 2. Set ACS URL to the Minerva ACS URL. 3. Set Audience or Entity ID to the Minerva Entity ID. 4. Set the login, portal, or app launch URL to the Minerva SSO launch URL. 5. Use email as the NameID value and assign the app to a test user or role. 6. Copy the OneLogin issuer, SSO URL, and signing certificate into Minerva. For SCIM: 1. Use a SCIM v2 connector when you want lifecycle provisioning. 2. Set SCIM Base URL to the Minerva SCIM base URL. 3. Set the authorization header or bearer token value to the Minerva token. 4. Enable user create, update, and deactivate actions. 5. Map role or group values to the same text configured in Minerva role mapping rules. Notes: * OneLogin has several SAML and SCIM connector templates. Select the one that supports both SAML sign-in and SCIM provisioning when you want one app. * Keep SCIM role values simple and stable, because Minerva matches the configured text values exactly after trimming whitespace. ## Rollout Checklist Use this checklist before changing production sign-in behavior: * SAML app is assigned to a pilot admin user or pilot group in the IdP * Entity ID and ACS URL in the IdP match the values shown in Minerva * IdP app tile, bookmark, or launch link opens the Minerva SSO launch URL * IdP issuer, SSO URL, and signing certificate are saved in Minerva * **Test SSO** succeeds in Minerva * SCIM base URL and bearer token are saved in the IdP * SCIM connection test succeeds in the IdP * pilot users are created or updated correctly by SCIM * role mapping values match the values sent by the IdP * a rollback path is available before switching to **SSO only** ## Common Issues | Issue | What to check | | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | SAML test fails before redirect | The SSO URL, IdP entity ID, or provider assignment may be incorrect. | | SAML response is rejected | The ACS URL, Entity ID, recipient/audience, NameID, or signing certificate may not match. | | Firebase says initial state is missing | Confirm the user started from Minerva or from the Minerva SSO launch URL. This usually happens when an IdP tile posts directly to the ACS URL. | | User signs in but is not expected | Confirm the user is assigned to the Minerva app in the IdP and has the right email address. | | SCIM connection test fails | Confirm the SCIM base URL, bearer token, and bearer-token authentication mode. | | SCIM users receive the wrong role | Confirm the IdP is sending the expected group, role, or entitlement value and that it exactly matches a Minerva role mapping rule. | | Users are still invited manually | If the IdP should own lifecycle management, enable SCIM provisioning and consider disabling dashboard-managed invitations while SCIM is enabled. | If an IdP label does not match this guide exactly, look for the equivalent SAML or SCIM concept. For example, **Reply URL**, **ACS URL**, and **Assertion Consumer Service URL** often refer to the same SAML endpoint. # Automatic Disposition Guide Source: https://docs.gominerva.com/automatic-disposition-guide How to configure and review beta automatic disposition predictions for potential screening matches. 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. **Beta feature:** 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. **Access:** Requires the **Admin** or **Owner** role. In the sidebar, go to **Administration** > **Configuration**, then open **Automatic Disposition** under **Post Processing Behaviours**. 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 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. ## 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 | | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | False match | 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. | | True match | 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. | | Undetermined | 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. | | Could not complete | 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 **Automatic Disposition** from tenant configuration. Select the workspace you want to configure before changing any settings. The page includes global enablement, workflow enablement, mode selection, thresholds, and optional prompt guidance. ### Global Enablement Turn on **Enable automatic disposition** 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 | | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | Onboarding | Potential matches created during initial customer or profile onboarding. | | Ongoing monitoring | Potential matches created by recurring monitoring checks for existing profiles. | | Direct API | 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 | | --------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- | | Default | Sends the standard match context needed for the prediction. | Use when your organization has approved normal model processing for screening review support. | | Anonymized | Reduces identifying detail while preserving enough structure for review. | Use when calibration can tolerate less direct identity context. | | Redacted | 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 | | ------------------------------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | Hint Mode | 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. | | Full Auto Mode | 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. 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. ## Tune Confidence Thresholds Each configured outcome has a confidence threshold from **0.00** to **1.00**. 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. The component shows: * whether the output was **Applied** or shown as a **Hint** * 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 **Applied** label means Minerva used Full Auto Mode and the prediction met the configured threshold. 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. 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 **Hint** label means Minerva did not change the match status. The prediction is shown as review context. 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. 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 **Administration** > **Configuration** > **Automatic Disposition**. 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 **Hint Mode**. 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 **Live**. 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. 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. ## 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) # Bulk Actions Guide Source: https://docs.gominerva.com/bulk-actions-guide How to use Screening bulk actions for large-scale match and profile updates. Bulk Actions lets your team apply the same update across a large screening working set without editing records one by one. **Access:** Requires the **Admin** role or above. In the sidebar, go to **Screening** > **Bulk actions**. Use this guide when you need to: * close or otherwise disposition many potential matches at once * archive stale, test, or accidental-upload profiles while preserving audit history * turn ongoing monitoring on or off for many profiles * add, move, or remove profile group assignments across a profile cohort * add the same operational comment to a large set of profiles * review, audit, or revert a prior bulk action Only users with **Owner** or **Admin** permissions can queue a bulk action or queue a reversion. Bulk Actions is designed for large asynchronous jobs, including jobs that affect up to **1,000,000 objects** in a single run. ## How Bulk Actions Works Every bulk action follows the same high-level sequence: 1. define the scope with the query builder and review the live preview 2. continue from the scope step so Minerva locks a durable execution snapshot 3. configure the primary action stage 4. optionally review the follow-up profiles preview and configure a follow-up profile stage when the primary stage targets potential matches 5. add a clear job name and rationale, then queue the job 6. track progress, review the audit workbook, and revert the job later if needed ## Key Concepts ### Scope and Snapshot Locking Bulk actions start with a live preview so you can confirm the right objects are included before anything changes. When you continue from the scope step, Minerva creates a durable execution snapshot. This matters because: * the worker processes the same set of records you reviewed * the audit workbook reflects that same snapshot * any follow-up stage derives its target set from that same locked snapshot ### Primary and Follow-up Stages The primary stage is where the main update happens. * If you target **potential matches**, the primary stage updates match review status. * If you target **profiles**, the primary stage can update profile status, monitoring state, archive state, profile group assignments, or add comments. For match-based jobs, Minerva can also run an optional **follow-up profile stage**. This is useful when: * you close many matches first * some profiles become fully cleared as a result * you want Minerva to continue directly onto those profiles and update their profile status or add a comment The follow-up stage can also be narrowed with an additional profile query before it runs. ### Follow-up Profiles Preview Before a follow-up profile stage is queued, Minerva shows a **profiles preview table** for the derived follow-up set. This preview reflects: * the locked snapshot from the scope step * the result of the primary match-status action * the rule that keeps only profiles that remain eligible for follow-up * any additional profile query you apply in the follow-up step Use this preview to: * confirm how many profiles would actually receive the follow-up actions * inspect which profiles are still included after the primary stage is applied * narrow the derived set further before changing profile status or adding comments * decide to skip the follow-up stage when no profiles remain eligible ### Audit and History Every bulk action records: * stage progress * per-object before-and-after snapshots * the user who requested the action * the job rationale * a downloadable XLSX audit workbook Profile workbook and audit rows include profile group IDs and profile group labels when a profile is assigned to one or more groups. Use Bulk Actions history when you need to: * confirm whether a job completed * inspect skipped or failed objects * review exactly what changed on each object * download evidence for internal review or audit support ## Example Use Cases ### 1. Bulk Disposition With Automatic Profile Follow-up Use this pattern when you need to close a large group of sanctions-related potential matches and automatically continue onto the affected profiles once those profiles no longer have unresolved matches. This example shows: * the follow-up step after a sanctions scope query has already been locked * the derived follow-up profiles preview table that appears before profile actions are selected * an additional profile query that narrows the derived profile set * follow-up profile actions that update the related profiles to **Accepted** * a shared profile comment that records the rationale for each accepted profile Use a clear job reason. That rationale appears in history and can also be reused inside bulk profile comments. ### 2. Bulk Disposition Of PEP Matches From One Source Use this pattern when a single PEP data source is generating a large cohort of potential matches that all need the same review outcome. This example shows: * a match-scoped query for unresolved **PEP** hits * a **PEP sources** filter set to **OpenSanctions Wikidata** * an optional date range to focus the job on a recent intake window * the live preview that confirms which matches the scoped job would affect This is a common workflow when your team wants to treat one incoming source consistently without affecting PEP matches from other sources. ### 3. Bulk Archive Of Old Rejected Profiles Use this pattern when you want to move a stale cohort out of the active working set without erasing the audit trail. Common archive cases include: * removing test profiles after implementation or UAT and before go-live * periodically cleaning up rejected profiles created on or before **April 18, 2024**, which is more than two years old as of **April 19, 2026** * containing an accidental mass upload by filtering to a tight created-at window or a shared upload attribute This example focuses on the periodic cleanup case. This example shows: * a profile query for active **Rejected** profiles * a created-at range capped to profiles created on or before **April 18, 2024** * the live preview that confirms which profiles the archive job would target Archiving changes the profile’s working-set state, but the archived profiles still remain available in history and audit surfaces. In the current workflow, archived profiles also leave ongoing monitoring downstream. ### 4. Bulk Profile Monitoring Update Use this pattern when a large number of profiles should come off ongoing monitoring because they share the same profile characteristics or workflow state. This example shows: * a profile query for monitored profiles * additional filters on profile status and kind * the live preview that confirms which profiles the update would remove from monitoring ### 5. Bulk Profile Group Assignment And Re-segmentation Use this pattern when another system, risk review, onboarding cleanup, or periodic refresh identifies many profiles that should receive the same profile group update. Bulk profile group actions are useful for: * adding an elevated-risk segment while keeping existing group assignments * moving profiles from a legacy or lower-risk segment into a replacement segment * aligning imported customers with risk, product, geography, or service-model groups * preparing profile populations for group-specific screening frequency overrides Choose **Add to groups** when the new segment should be layered onto the profile without removing other meaningful assignments. Choose **Move to groups** when the selected groups should become the profile's replacement group set. This assignment example shows: * a profile query filtered to existing profile groups and accepted profiles * the live profile preview that confirms the cohort before the snapshot is locked * a profile action that adds the selected profiles to **Enhanced diligence** * a multi-select control that supports assigning profiles to more than one group when needed This move example shows: * a profile query scoped to profiles in retail standard or cross-border commercial groups * the same live preview pattern operators review before locking the job snapshot * an action that moves the selected profiles into **Enhanced diligence** as the replacement group set Use **Remove from profile groups** when you need to remove selected groups. Choose **All assigned groups** to clear every profile group assignment for the selected profiles. Use **Move to groups** carefully. It replaces the selected profiles' current group assignments with the groups chosen in the action. ### 6. Bulk Profile Comment Use this pattern when many profiles need the same analyst note, case-handling instruction, or operational reminder. This example shows: * a profile query for active escalated profiles * the live preview that confirms which escalated profiles the shared note would reach * the scoped cohort before adding a shared comment template that can include the queued job reason ## Reverting A Bulk Action Most current bulk actions are reversible, including: * match status updates * profile status updates * profile monitoring updates * profile archive updates * profile group assignment updates * bulk-added profile comments When you preview a reversion, Minerva compares the live object to the post-action state captured by the original job. If nothing changed after the original bulk action, Minerva can restore the previous state directly. If something changed in the meantime, Minerva marks that object as a conflict and lets you choose how to handle it. The conflict strategies are: * **Fail on conflict**: stop that object from being reverted until it is reviewed * **Leave current state**: skip that object and keep the current live value * **Restore previous state**: overwrite the current value with the stored prior value Common conflict examples include: * a match was reopened after the bulk action completed * a profile status changed after the original job ran * monitoring was changed by another workflow * profile group assignments were changed by another workflow or API integration * a bulk-added comment was edited or deleted before the reversion ran The live reversion flow usually looks like this: 1. open the completed source job from **Bulk Actions history** 2. preview the reversion to confirm how many items can be restored cleanly 3. if conflicts exist, choose a default strategy and optionally override the sampled rows before queueing ### Reversion Entry Point Start from the completed source job in Bulk Actions history. The job drawer shows the stored item snapshots, the audit workbook, and the **Preview reversion** action for reversible jobs. ### Reversion Preview Without Conflicts When nothing drifted after the original job completed, the preview confirms that the stored previous state can be replayed directly. In that case, add a clear reason and queue the reversion. ### Reversion Preview With Conflicts If Minerva detects drift, it samples the conflicting rows so you can see which field changed and decide how to handle it. The sample is representative rather than exhaustive, so treat the preview counts as the full scope and the table as the review aid for choosing a strategy. Reversion is launched from **Bulk Actions history** after you open a completed job. Preview the reversion first so you can review any conflicts before queueing the restore job. ## Best Practices * Start with the narrowest query that captures the intended cohort. * Review the live preview before you continue to the locked snapshot. * Use a specific job name and rationale so history remains easy to audit later. * Use follow-up profile stages only when the profile action truly depends on the result of the primary match action. * Use profile group filters when the intended profile cohort is defined by risk segment, product segment, or another workspace-scoped group. * Preview reversion before restoring a prior bulk action, especially if the underlying profiles or matches may have changed since the original job ran. ## Related Guides * [Screening Guide](/screening-guide) * [Profile Groups Guide](/profile-groups-guide) * [Dashboards Guide](/dashboards-guide) * [Risk Assessment Flow](/risk-assessment-flow) # Adverse Media Source: https://docs.gominerva.com/concepts/adverse-media An introduction to adverse media at Minerva ## Overview Minerva uses publicly available data from over 250,000 reputable and relevant news sources including national & regional outlets, radio, television and video news sites, professional journals, and blogs in 147 languages. ## How do we find adverse media and detect risk? Minerva uses trained machine-learning models to evaluate new articles in real time through the UI and API. Our AI models conduct sentiment and risk analysis for each article that may pertain to the subject of the search: * **Sentiment analysis** is responsible for determining the tone of the article as "negative", "positive", or "neutral" * **Risk analysis** scores the supported financial and non-financial adverse media categories that are enabled for the applicable workspace and screening channel Sentiment and risk analysis work together to strengthen the overall adverse media result. Role-aware adverse media can add another article-level signal by checking whether a negative article appears to involve the screened subject or is likely only a name mention. For configuration details, see the [Role-Aware Adverse Media Guide](/role-aware-adverse-media-guide). ## Adverse Media Categories Minerva supports 32 category keys. The standard configuration enables 28 financial crime categories and the legacy **Other (Non-Financial)** category. **DUI**, **Property Damage**, and **Assault and Battery** are available but disabled by default so they do not appear unexpectedly in existing integrations. Administrators can add or remove categories independently for **Onboarding**, **Ongoing Monitoring**, **Direct API Calls**, and **Risk Assessments**. API integrations can also override the category set for one synchronous search or one entity in a batch. See [Adverse Media Categories](/adverse-media-categories) for: * the complete financial and non-financial category reference * the AML scope of financial crime adverse media * workspace and four-channel configuration steps * request-level `search-sync` and batch search overrides # Data Feeds Source: https://docs.gominerva.com/concepts/data-feeds An introduction to Minerva data feeds ## Overview Minerva provides a wide range of data feeds to help you assess Anti-Money Laundering (AML) risk quickly and accurately. By choosing the right data feeds, you can tailor your search to fit your review objectives - whether you need a focused check or a comprehensive Enhanced Due Diligence (EDD) review. ### Feed Breakdown Minerva currently supports these core data feeds, each serving a distinct function within compliance and investigative workflows: * **Sanctions**\ Screens subjects against global sanctions lists (e.g., OFAC, EU, HMT, UN) to identify matches with designated or restricted individuals and entities. Used primarily for anti-money laundering (AML) and regulatory compliance. Updates can be as frequent as every six hours for key lists. * **PEP (Politically Exposed Persons)**\ Identifies individuals holding or having held prominent public positions (e.g., government officials, heads of state) and their close associates. Sourced from databases like Peppercat, Rulers.org, EveryPolitician. See [PEP Policy](/concepts/pep-policy) for Minerva's inclusion and classification standard. * **Criminal**\ Surfaces criminal records, charges, and involvement in criminal activities for subjects under review. Supports risk profiling and background checks. * **Legal**\ Reports involvement in civil or criminal litigation, including lawsuits and judgments, giving insight into reputational or legal risks. * **News (Adverse Media)**\ Gathers news and media mentions indicating adverse activities, such as fraud or regulatory violations. Aggregates 200,000+ outlets in 147+ languages, updating as quickly as every 10 minutes. * **Offshore**\ Flags presence in offshore leaks (e.g., Panama Papers), exposing hidden company ownership or shell entity connections related to the search subject. * **Ownership**\ Reveals beneficial ownership relationships and structures for individuals and entities. Often used for corporate due diligence and transparency. * **Registries**\ Searches official government or commercial registries (including Equifax Individuals data in the U.S.) for verified identity information: name, address, SSN, etc. Used for validation and to reduce false positives, especially in EDD. * **Social Media**\ Retrieves publicly available business or individual profiles from social platforms (e.g., LinkedIn, Facebook) to verify affiliations and online presence. Note: Only public information is retrievable; privacy limitations often apply. * **Open Source**\ Mines other web-based public and open data (including blogs, forums, and lesser-known registries) for additional context - not covered by the above feeds. Automatically included if PEP is selected unless specifically omitted. See the [Risk Inference Guide](/risk-inference-guide) for how sourced Open Source text can contribute PEP, Criminal, and High Risk Industry signals. **How they work together:** * All feeds collaborate to create a rich, context-driven risk profile for each search subject using advanced entity resolution and knowledge graph techniques. * Feeds can be enabled or limited per user or organizational settings, tailoring screening to specific compliance needs. # PEP Policy Source: https://docs.gominerva.com/concepts/pep-policy Minerva policy for defining, classifying, and retaining politically exposed person data ## Purpose This policy defines how Minerva identifies, ingests, classifies, and retains Politically Exposed Person (PEP) data when using third-party source data, including OpenSanctions, as an upstream input. The goal is to ensure Minerva has a clear, defensible, and operationally useful standard for: * what qualifies as a PEP * what related persons are included * how records are classified * how long records remain in scope * how external source data is translated into Minerva's internal policy ## Policy objective Minerva ingests PEP-related data from external providers. Because external datasets are designed for broad coverage and not necessarily for one-to-one operational use in Minerva, source data must be normalized into a Minerva-defined policy standard. Minerva therefore treats upstream source definitions as an input, not as the final policy authority. ## Minerva definition of a PEP Minerva defines a Politically Exposed Person as: A natural person who currently holds, or previously held within the applicable lookback period, a prominent public function, and whose role, jurisdiction, or level of authority creates elevated corruption, bribery, sanctions evasion, money laundering, or influence risk. This includes persons holding qualifying roles at the national, intergovernmental, regional, sub-national, and relevant local level, as well as certain senior persons connected to state-owned enterprises, public agencies, diplomatic functions, security institutions, and political parties. Minerva separately recognizes Relatives and Close Associates (RCA) of qualifying PEPs, but does not treat them as office-holding PEPs. RCA records are included as a distinct classification. ## Guiding principles Minerva's PEP policy is based on the following principles: * **Role-based inclusion**\ A person is included because they occupy or occupied a qualifying position, not merely because they are politically adjacent. * **Risk-based scope**\ The higher the level of public authority, access to state resources, regulatory influence, or political control, the stronger the presumption of inclusion. * **Separate treatment of RCA**\ Family members and close associates of PEPs are relevant to compliance risk, but are classified separately from the office-holder. * **Coverage with controlled precision**\ Upstream source data may contain newly created or partially classified roles. Minerva should not depend solely on perfectly tagged categories when determining scope. * **Explainability**\ Every included record should, where possible, be traceable to a role, jurisdiction, time period, and source rationale. ## Evidence and source evaluation Minerva evaluates PEP inclusion based on credible evidence of public office, role occupancy, relationship data, jurisdiction, and timing. Minerva may ingest data from third-party sources, public records, corporate records, official websites, and other research inputs, but Minerva applies its own internal policy standard when determining whether a person should be included. Some PEP determinations are straightforward, particularly where a qualifying office can be tied to an official title, term, and jurisdiction. Other determinations are more subjective, especially in the case of relatives and close associates. Where Minerva is able to identify compelling evidence, supporting references, or credible source material showing that a person is a relative or close associate of a qualifying PEP, Minerva may include that individual as an RCA under its policy. However, a passing mention in a news article, an unsupported reference to a relationship, or a speculative association does not automatically justify PEP inclusion at Minerva. Relationship-based inclusion requires sufficient supporting evidence to make the classification defensible. Minerva's objective is not simply to assign a label. The goal is to provide enough supporting documentation, source references, and linked evidence so that, in the event of an alert, the client has sufficient context to review and action the result. ## Primary inclusion categories The following categories are included in Minerva's PEP universe by default. ### 1. National government and state leadership Included: * Head of state * Head of government * National executive and cabinet members * National legislature members * Senior national court judges and prosecutors * Senior military, police, intelligence, and security leadership * Central bank leadership * Ambassadors and senior diplomatic leadership **Rationale:** These roles represent the clearest and most widely recognized PEP categories due to political authority, decision-making power, influence over public resources, and corruption exposure. ### 2. Intergovernmental organization leadership Included: * Senior leadership of intergovernmental organizations * Legislators or equivalent senior governing officers of intergovernmental bodies where relevant **Rationale:** These roles may involve influence over public policy, cross-border funding, diplomatic authority, or international regulatory decision-making. ### 3. Regional or sub-national public office Included: * Governors, premiers, and equivalent regional heads of government * Regional executive and cabinet members * Regional legislature members * Senior regional judges **Rationale:** These roles may control substantial public budgets, procurement, regulation, licensing, and politically sensitive administrative decisions. ### 4. Relevant local public office Included: * Mayors and equivalent local heads of government * Members of local executive bodies * Local legislators or council members where the role has meaningful public authority **Rationale:** Local office is in scope where the role has real influence over public funds, procurement, land use, licensing, municipal services, policing, or politically exposed decision-making. Not every local public servant is in scope. Minerva distinguishes between politically significant local office and lower-risk municipal administration. ### 5. State-owned enterprises and public agencies Included: * Senior executives * Board members * Other senior decision-makers of state-owned enterprises, sovereign entities, and public agencies reporting to government **Rationale:** These individuals may exercise control over public assets, procurement, contracts, state resources, licensing, and politically sensitive commercial decisions. ### 6. Political party leadership Included: * Senior leaders of political parties * Other high-ranking party officials where the role indicates material political influence **Rationale:** Senior party leadership may carry influence over candidate selection, policy direction, patronage, government formation, or state access. ## Relatives and Close Associates Minerva includes relatives and close associates of qualifying PEPs when supported by source evidence or policy rules. RCA records are classified separately from PEP office-holders. RCA may include: * spouses or partners * children * parents * siblings * other close family members where relevant * known business associates * trusted intermediaries or nominees * other close associates linked by a credible relationship to the PEP ### RCA classification rule A relative or close associate is not itself treated as an office-holder PEP unless that person independently holds a qualifying PEP office. ## Explicit exclusions The following are excluded from Minerva's default PEP scope unless a client-specific policy requires broader treatment: * ordinary civil servants without meaningful public decision-making authority * low-level municipal staff * junior employees of public agencies or state-owned enterprises * administrative or clerical personnel without public authority * individuals who are politically adjacent but hold no qualifying office and have no supported RCA relationship * persons lacking sufficient identity, role, or timing evidence ## Inclusion timing and lookback rules Minerva uses a role-sensitive lookback approach. ### Default lookback periods * National positions: 20 years after leaving office * Intergovernmental positions: 20 years after leaving office * All other qualifying positions: 5 years after leaving office These windows govern whether a record remains actively in scope for Minerva's PEP classification unless stricter customer policy or jurisdiction-specific requirements apply. ### If end dates are unavailable Where source data does not provide reliable end dates, Minerva may classify the status as unclear and retain the record temporarily where there is sufficient evidence that the person held a qualifying position. Where there is no usable birth date, death date, role timing, or other basis for determining current or historical relevance, the record should be excluded from active policy scope. ## Ingestion and normalization rules When Minerva ingests upstream or third-party PEP-related data, the following rules apply: * records identified as PEP candidates should be treated as upstream signals for Minerva review * relatives and close associates should be classified separately from office-holders * position and occupancy data should be used to determine role type, jurisdiction, and timing * Minerva should not rely solely on a single mention, weak association, or incomplete third-party tag when determining final inclusion * where classification is incomplete, Minerva may retain the record for review if there is credible evidence of a qualifying role or relationship * Minerva must apply its own exclusion, confidence, identity-resolution, and timing logic before exposing records downstream * Minerva should seek to preserve sufficient supporting documentation, source references, and links so clients can understand and action a resulting alert ## Operational policy for ambiguous records Where a record appears politically relevant but classification is incomplete, Minerva should: * retain the record for review if there is credible evidence of a qualifying position * classify it as unclear where status cannot be confidently determined * avoid suppressing the record solely because detailed source taxonomy is not yet complete * exclude only where there is sufficient evidence that the person is outside Minerva's policy scope ## Policy statement Minerva's PEP definition and inclusion standard is based on a role-based, risk-sensitive approach. Upstream data sources are used as ingestion inputs and research references, but Minerva applies its own internal normalization, exclusion rules, evidence standards, and status model to determine active policy scope. In practice, Minerva includes qualifying public office-holders across national, intergovernmental, regional, and relevant local government, as well as senior persons in state-linked entities and political parties. Minerva also includes relatives and close associates of qualifying PEPs as a distinct RCA class where supported by sufficient evidence. Minerva's default global policy is intentionally broader than some jurisdiction-specific regulatory definitions. Results should be understood as identification and screening signals, not automatic legal conclusions. Minerva can also apply jurisdiction-specific overlays, including FINTRAC, FinCEN / U.S., and UK identification views, to help clients map Minerva records to the categories most relevant to their regulatory obligations. This policy is intended to create a defensible, explainable, and operationally consistent foundation for Minerva's PEP screening and risk workflows. # Profile Groups Source: https://docs.gominerva.com/concepts/profile-groups Workspace-scoped dynamic segmentation for monitored profiles. Profile groups are workspace-scoped segments for monitored profiles. They let an organization group customers by internal criteria such as risk tier, product exposure, geography, service model, or diligence requirements without creating a new workspace for each population. Use profile groups when: * the segmentation can change over time * a profile can belong to more than one segment * the segment should be visible to analysts and admins * ongoing monitoring cadence may differ by segment Profile groups are different from workspaces: | Concept | Use it for | | ------------------------------ | ----------------------------------------------------------------------------------------------------------- | | Workspace | A logical operating context such as Live, Calibration, or a separate integration environment. | | Profile group | A dynamic customer population inside a workspace, such as Enhanced diligence or Retail standard monitoring. | Each profile group has a system-generated internal ID. Admins manage the customer-facing name, description, priority, and archived status. API integrations should use the generated ID, not the label. Priority is used when a profile belongs to multiple groups. Higher priority groups win for profile group-specific monitoring frequency overrides. If no group override applies, the profile uses the workspace default. For setup instructions and examples, see the [Profile Groups Guide](/profile-groups-guide) and [Screening Frequencies Guide](/screening-frequencies-guide). # Risk Rating Source: https://docs.gominerva.com/concepts/risk-rating An introduction to risk rating with Minerva ## Overview Minerva has created a proprietary customer risk rating (CRR) engine which takes a multifactor approach to scoring client risk. This includes hard binary criteria such as the presence of an individual or entity on a global terror, sanctions, or criminal watchlists, as well as inferred criteria such as criminal status or political exposure from unstructured notes and listed occupations. The entire profile is considered when assigning a CRR score to it, and includes all fields from social media, global news, watchlists, registries, independent journalism, open-source web pages, legal databases, and business registries. The score is normalized out of 100, with default risk classification breakpoints at 33 and 66 (where the next category score is greater than or equal to that of the previous breakpoint). For details on how workspace settings control text-derived PEP, Criminal, and High Risk Industry signals, see the [Risk Inference Guide](/risk-inference-guide). ## CRR Criteria Categories The CRR criteria are separated into 3 categories: 1. **Dynamic**: Criteria which apply to the unique characteristics of the profile being analyzed and are subject to change between profiles. 2. **Organizational**: Criteria which are static between profile searches but differ between the institutions performing the search. The out-of-box solution is set with the defaults listed in Appendix S2 and can be configured at request. 3. **Contributed**: Criteria which the end user can modulate based on their unique knowledge, the knowledge of their institutions, or their unique understanding of the profile being analyzed. The CRR criteria enable stratification of the calculated risk scores based on their degrees of freedom: * Dynamic criteria have the highest degrees of freedom due to the range of possible profiles that may present themselves to the algorithm. * Contributed criteria vary based on the interpretation of the end user and their unique knowledge of the profile, which may or may not be applicable in every search case. * Organizational criteria have the lowest degrees of freedom, and typically only vary among the institutions of the customer base and are unlikely to change through time unless the business practices of the end user’s organization dramatically change. ## Risk Categories and Weightings ### Dynamic Factors | Code | Criteria | Formula | Score | | ---- | -------------------------------------------- | -------------------- | ----- | | 1 | Sanctions list match | Soft name match | 100\* | | 2 | Sanctioned geography (FATF blacklisted) | Geography match | 100\* | | 3 | Politically-exposed persons (PEP) list match | Soft name match | 100\* | | 4 | PEP status inferred from profile | Contextual inference | 25 | | 5 | High-risk business inferred from profile | Contextual inference | 25 | | 6 | High-risk (FATF greylisted) geography | Geography match | 15 | | 7 | Offshore assets discovered | Soft name match | 10 | | 8 | Adverse media discovered (N number of URLs) | max(1, 0.02N) | 0–50 | | 9 | Public exposure index (N number of URLs) | max(1, 0.1N) | 0–10 | | 16 | Criminal status inferred from profile | Contextual inference | 25 | | 17 | Criminal list match | Soft name match | 100\* | | 19 | Involvement in high-risk legal cases | Soft name match | 25 | ### Organizational Factors | Code | Criteria | Formula | Score | | ---- | --------------------------------------------------------- | ------------ | ----- | | 10 | Organization supports remote transactions | Configurable | 5 | | 11 | Organization processes transactions through third parties | Configurable | 5 | | 12 | Emphasis on fast and/or anonymous transfers | Configurable | 5 | | 13 | Organization facilitates cross-border transactions | Configurable | 5 | ### Contributed Factors | Code | Criteria | Formula | Score | | ---- | ------------------------------------------ | ---------------- | ---------- | | 14 | Previous SAR/STR filed | User-contributed | 10 | | 15 | Known cash/crypto intensive business (CIB) | User-contributed | 5 | | 18 | User Override (Low/Medium/High)\*\* | User-contributed | 0/50/100\* | \* Categories that override the total score to equal 100 (High). \*\* The User Override function will allow the user to override the Minerva score to either Low, Medium, or High. The user must enter a rationale for the override for audit purposes, and in alignment with the organization’s risk assessment policy. # Sanctions Source: https://docs.gominerva.com/concepts/sanctions An introduction to sanctions screening with Minerva ## Overview This guide outlines the various lists that flag in our Sanctions category, including FATF country ratings along with our data validation approach to ensure our lists are always up to date. ## How does Minerva perform Sanctions screening? When the Sanctions data category is selected during the search process, Minerva performs in-depth screening of all critical globally recognized sanctions designation lists using the legal name of the individual or organization being searched. By adding additional information to the search such as date of birth (individuals) or registration number/date of registration (organizations), this will increase the probability of a potential match and help to manage false positives. For all searches, the Sanctions Screening List section of the report provides a detailed listing of all the sources that were screened as part of the search regardless of outcome. Here are the key Sanctions and Watchlists that Minerva scans when the Sanctions feed is selected during a search. The following list is not comprehensive: * **Canada** * Canadian Autonomous Sanctions List which includes: * Justice for Victims of Corrupt Foreign Officials Regulations (JVCFOR - Canada) * Special Economic Measures Act List (SEMA – Canada) * Freezing Assets of Corrupt Foreign Officials Act (FACFO Act –Canada) * Listed Terrorist Entities (groups and individuals) designated under the Regulations Establishing a List of Entities (RELE – Public Safety Canada, often referred to as Criminal Code or SOR 2002/284) * **United States** * International Trade Association Consolidated Screening List (13 key sanctions lists including the BIS, SDN and Non-SDN Lists) * Consolidated Sanctions List (Non-SDN) List * Specially Designated Nationals (SDN) List * Bureau of Industry and Security (BIS) Denied Persons List * FBI “Most Wanted” (Watchlists) * Hijack Suspects List * Terrorist List (includes Domestic Terrorists) * **Australia** * Department of Foreign Affairs and Trade (DFAT) Consolidated Sanctions List * **European Union** * European External Action Service (EEAS) Sanctions List * **FATF (Watchlists)** * Blacklisted (High Risk) Jurisdictions * Greylisted (Increased Monitoring) Jurisdictions * **France** * France uses a single list that includes the EU (EEAS) and UN lists along with the France National Assets freezing lists found at the Ministry of Economics and Finance – France DG Tresor list * **Switzerland** * Swiss State Secretariat for Economic Affairs (SECO) Sanctions List * **Ukraine** * Ukraine State Financial Monitoring Service (SDFM) Blacklist * **United Kingdom** * Her Majesty’s Treasury Sanctions List * **United Nations** * United Nations Security Council Consolidated List (UNSC List) – Used by UN member nations (e.g., Canada, EU etc.) ## List Update and Management Process: Minerva makes it easy for customers to stay up to date with the rapid pace of sanctions list changes. By automatically ingesting and updating each list nightly, directly from its source, we ensure that the most current information is available for our customers. Data ingestion logs are reviewed bi-weekly to ensure there are no loading errors and lists are sample tested (internally audited) at least once per year. ### Internal Testing Process When a new list is ingested: In our QA environment, a random sample of 5-10 individuals and entities that are “positively identified” on each list is selected and searched with the expected result of a Sanction flag. Reports are generated and the report audit trail is validated to ensure that the referenced list information within the report is correct. Screenshots are taken and stored with each test case. A control sample of subjects who should not appear flagged for sanctions is also reviewed. Once the testing has been approved in the QA environment, it is promoted to the production environment. ### Ongoing Validation In our Production environment, for each list, a random sample of 5-10 individuals and entities (as applicable) that are "positively identified" are selected and searched with the expected result of a Sanction flag. Where the subject has been removed, we would expect to see no sanction flag for that search result. Reports are generated and the report audit trail is validated to ensure that the referenced list information within the report is correct. Screenshots are taken and stored with each test case. A control sample of subjects who should not appear flagged for sanctions is also reviewed. ### FATF Countries Lists FATF lists are updated manually. Minerva belongs to the FATF notification system and proactively checks the FATF lists monthly. Once the list is updated, Minerva uses the testing approach referenced to sample 2-5 individuals or entities from each added or removed country and confirms alignment to the correct score within the risk rating (High Risk, Increased Monitoring). # Custom Lists Guide Source: https://docs.gominerva.com/custom-lists-guide How to manage tenant-owned screening lists: upload records, publish versions, activate lists per workspace, and control risk rating impact. Custom lists let your organization screen customers against internal watchlists, do-not-onboard registries, and other tenant-owned lists. They screen alongside Minerva's standard Sanctions, PEP, and News feeds. Records you upload become a versioned, deployable screening source with full audit history. **Enterprise feature:** Custom lists are available for enterprise customers and must be enabled by Minerva before your organization can use them. Contact your Minerva representative or [support@gominerva.com](mailto:support@gominerva.com) to discuss enabling custom-list screening for your environments. **Access:** Requires the **Admin** role or above to create lists, upload records, publish versions, or change workspace activation. Other users can review lists read-only. In the sidebar, go to **Administration** > **Configuration**, then open **Custom Lists** under **Data sources**. Use this guide when you need to: * create a custom list and upload records in bulk * add, edit, or archive individual records * publish reviewed versions of a list * activate a list version for a workspace screening feed * control how list matches affect the Client Risk Rating * monitor deployment health and roll back to an earlier version Custom lists are **tenant-owned**, while activation is **workspace-scoped**. The same list can be live in one workspace (for example Live) while another workspace (for example Calibration) stays on an older version or does not use the list at all. ## Key Concepts | Concept | Meaning | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | List | A tenant-owned collection of records with a name, description, and risk rating impact. | | Record | One individual or organization on the list, identified by a stable record UID from your source system. | | Working set | The current editable records and list settings. Manual edits and list-setting changes accumulate here until you publish changes; bulk uploads publish in their own review step. | | Version | An immutable snapshot created by publishing the working set. Only published versions can be activated. | | Activation | The workspace-level choice of which published version screens live traffic, and on which feed category. | | Feed category | The screening feed a match is reported under: Internal Risk, Sanctions, PEP, News, Legal, or Criminal. | | Deployment | The background rollout that indexes an activated version and brings it into live screening. | ## How Custom List Screening Works 1. **Create a list** and load records through file uploads or manual entry. 2. **Publish** the working set into a new immutable version after reviewing the staged changes. 3. **Activate** a published version in the selected workspace on a feed category. 4. Minerva **deploys** the version. When the deployment is live, screening and ongoing monitoring in that workspace include the list. 5. Matches appear in screening results under the selected feed category with the list name, record UID, and your custom fields as evidence, and the list's risk rating impact is applied to the profile's Client Risk Rating. ## The Custom List Management Page The management page shows every list in the tenant with its deployment state, workspace activation, feed category, record count, and latest version. From this page you can: * **Create list**: name the list, describe it, and choose its default feed category. * **Download upload templates**: starter CSV or XLSX files with the recognized column headers. * **Open** a list to manage records, uploads, versions, and activation on its detail page. * **Upload** directly into a list from the table row. ## The List Detail Page Each list has a detail page with four areas: the records table, the risk rating impact control, deployment status, and recent uploads. ### Records The records table is the list's working set. Manual edits become part of the next published version. * Filter by record status (**Active** or **Archived**). * Search by record UID prefix. * **Add record** or **Edit** opens the record form: record UID, entity type (individual or organization), name, aliases, countries, date of birth or date of incorporation, reason, notes, and custom fields. * **Archive** removes a record from the next published version without deleting its history; archived records can be restored. Use a stable identifier from your source system (customer number, case ID) as the record UID. Uploads match records by UID, so a stable UID is what makes re-uploads update records instead of duplicating them. ## Uploading Records in Bulk Use **Upload records** on the detail page to load a CSV or XLSX file of up to 100MB. Columns can be in any order when the headers are recognizable; start from the downloadable templates if you are building the file for the first time. Every upload is validated on the server before anything changes: 1. Choose the file and a **merge mode**: **Upsert only** keeps records that are missing from the file, while **Full replace** archives them. 2. **Validate** parses the file and computes an execution plan (adds, updates, unchanged records, and archives) without applying anything. 3. Review the plan, the row preview, and any validation errors. 4. **Publish** applies the batch and creates a new published version of the list. If validation reports errors, fix the file and upload it again. Nothing from a failed or unreviewed batch reaches screening. In-progress and recent batches stay visible in **Recent Uploads** so another admin can pick up a pending review. ## Publishing Changes Manual record edits and list-setting changes (name, description, risk rating impact) accumulate as unpublished changes. The list header shows an **Unpublished changes** chip while anything is staged. **Publish changes** snapshots the working set into a new version and deploys it where the list is activated. The review dialog summarizes exactly what will change: * added, updated, and removed record counts, with a sample of affected records * list configuration changes, such as a new risk rating impact * the total record count after publish Use **Discard changes** in the header menu to reset the working set back to the last published version instead. Publishing does not interrupt screening. The previously active version keeps serving until the new version's deployment is live. ## Activating a List in a Workspace Activation controls which published version screens live traffic in the selected workspace. Open **Manage activation** (or **Activate in workspace** for a list that is not active yet). * **Feed category** chooses the screening feed this list contributes matches to: Internal Risk, Sanctions, PEP, News, Legal, or Criminal. * **Target version** selects the published version to serve. Draft or failed versions cannot be activated. * **Disable** stops the list from screening in this workspace without deleting the list or its versions. Activation requests a deployment. Screening starts once the deployment status reaches **Live**; the deployment status card on the detail page tracks each step (version published, deployment queued, provisioning and indexing, live) and surfaces failure reasons with retry. Activation is per workspace. Activating a new version in Live does not change what Calibration serves. Switch workspaces and activate there when you are ready. ## Risk Rating Impact The **Risk rating impact** slider (0–100) controls how much a screening match against this list raises the profile's Client Risk Rating: 0 means no risk-rating effect and 100 means a match immediately reads as high risk. The value is saved to the working set and takes effect on screening when you publish changes. Use higher impacts for lists that represent confirmed adverse decisions (do-not-onboard, exited relationships) and lower impacts for advisory or contextual lists. ## Version History and Rollback Every publish creates a numbered version with its record count, risk impact, publish time, and deployment state. Open **Version history** from the header menu to review or roll back. Activating an older version rolls the workspace back without deleting newer published versions, so you can roll forward again at any time. Rollback is also the recovery path when a deployment fails: retry the failed version, roll back to the last good one, or disable the feed while you investigate. ## How Matches Appear in Screening * Matches from custom lists appear in screening results and ongoing monitoring under the feed category the list is activated on, alongside matches from Minerva's standard data feeds. * Match evidence includes the list name, the record UID, and the custom fields you uploaded, so reviewers see why the record is on the list. * The monitoring cadence for the Internal Risk feed is configured on the Screening frequencies page once custom lists are enabled for the tenant. ## Example Use Cases | Use case | Feed category | Suggested setup | | ------------------------ | ------------- | --------------------------------------------------------------------------------------------------- | | Internal watchlist | Internal Risk | Upsert-only uploads from case management; moderate risk impact; daily-to-weekly monitoring cadence. | | Do-not-onboard registry | Internal Risk | Full-replace uploads from the decision system of record; high risk impact. | | Policy sanctions overlay | Sanctions | Entities restricted by internal policy beyond public programs; high risk impact. | | Litigation exposure | Legal | Counterparties in active disputes; low-to-moderate impact for context during review. | ## Related Guides * [Screening Guide](/screening-guide) * [Screening Frequencies Guide](/screening-frequencies-guide) * [Workspaces Guide](/workspaces-guide) * [Match Scoring Guide](/match-scoring-guide) # Dashboards Guide Source: https://docs.gominerva.com/dashboards-guide How to use Dashboards The Dashboards section provides a high-level view of screening workload and profile monitoring trends. ## When to Use This Guide Use this guide when you need to: * review screening priorities at a glance * jump directly into filtered profile queues that need attention * monitor profile and workflow trends over time * see how many profiles are monitored, unmonitored, or awaiting review ## Before You Begin * Confirm you have access to the **Dashboards** section * Make sure your organization already has screening or risk assessment activity in Minerva ## Main Areas ### Overview The **Overview** page is designed to help you quickly understand what needs attention now. Use it to review: * **Profiles with risk**, broken down into: * Sanctions * Politically Exposed Persons (PEPs) * Adverse media * **Priority status**, broken down into: * Potential matches * In review * Escalation * **Recent risk assessments** The risk and priority rows are clickable and take you directly into filtered **Screening** profile views. The recent risk assessments table takes you into **Risk Assessments** history for the selected item. ### Screening Analytics The **Screening analytics** page is currently focused on **Profiles** analytics. Use it to review: * **Current snapshot** metrics, including: * total profiles in system * monitored profiles * unmonitored profiles * potential matches * not screened * in review * escalated * accepted * rejected * no flags * **Profiles over selected period** * **Profile status breakdown over time** * **Total vs monitored profiles over time** The analytics page also shows the last refresh time for the data currently displayed. ## How to Work With Dashboards Start with **Overview** when you want to identify immediate operational priorities and move quickly into the correct screening queue. Use **Screening analytics** when you want to understand profile growth, monitoring coverage, and workflow trends over time. ## Expected Result At the end of this workflow, you should have: * a current view of profiles and statuses that need attention * a clearer understanding of monitoring and workflow trends * enough context to move into detailed Screening or Risk Assessment workflows ## Related Guides * [Minerva App](/minerva-app) * [Screening Guide](/screening-guide) * [Risk Assessment Flow](/risk-assessment-flow) # Exports Guide Source: https://docs.gominerva.com/exports-guide How to export screening profiles and potential matches for analytics, visibility, and audit workflows. Exports let your team create downloadable XLSX workbooks from screening profiles and potential matches without changing any live screening records. **Access:** Requires the **Admin** role or above. In the sidebar, go to **Screening** > **Export**. Use this guide when you need to: * export potential matches for analytics, calibration, or operational reporting * export profiles for visibility, customer operations, or audit sampling * include associated profiles for a potential-match export * include profile group IDs and labels for segmentation reporting * control whether PII columns are included in a workbook * understand how exported match scores, scoring thresholds, and News retrieval settings affect the data you are analyzing * review export history and download completed workbooks Exports use the same durable preview, job, history, and workbook infrastructure as Bulk Actions, but export jobs are **non-mutating**. The export stage records selected rows and produces a workbook; it does not update match status, profile status, monitoring, archive state, or comments. Treat PII controls deliberately. If a stage is not opted into PII, PII columns are omitted or left blank for that stage in the workbook. ## How Exports Work Every export follows the same high-level sequence: 1. define the primary scope with the screening query builder 2. review the live preview table 3. continue from the scope step to lock a durable snapshot 4. optionally add an associated profile export stage when the primary scope targets potential matches 5. add a clear export name and rationale 6. queue the export and download the workbook from Export history after it completes ## Key Concepts ### Scope And Snapshot Locking The scope step shows a live preview so you can confirm the cohort before a workbook is queued. When you continue from the scope step, Minerva locks a durable preview snapshot. That snapshot matters because: * the export worker uses the same selected rows you reviewed * the workbook is generated from the locked export snapshot * history and per-row job items refer back to the same stage definition * associated profile stages derive from the locked match snapshot, not from a later live re-query ### Export Stages An export job can contain: * a **primary match export** stage * a **primary profile export** stage * an optional **associated profile export** stage when the primary stage targets potential matches Each stage has a single `export_selection` action. This is what makes exports different from Bulk Actions: the job records selected rows for workbook generation and does not call downstream profile or match mutation endpoints. ### PII Controls PII is controlled per export stage. * If a match stage opts into PII, the match sheet can include fields such as name, gender, nationality, occupation, organization, dates, locations, and aliases. * If a profile stage opts into PII, the profile sheet can include fields such as name, date of birth, contact details, address, nationality, occupation, and organization. * If one stage on a sheet includes PII and another does not, the workbook keeps the sheet rectangular but leaves PII cells blank for stages that did not opt in. Use the smallest PII scope that supports the purpose of the export. ### Workbook Output Completed export workbooks include: * a **Summary** sheet with job, requester, stage, status, and count metadata * one or more **Matches** sheets for exported potential matches * one or more **Profiles** sheets for exported profiles * per-row status, error, processed time, and deep links back into Minerva For match exports, workbook columns can include identifiers, review status, entity type, source flags, sanctions/PEP/News source names, match score, PEP level, media URLs, client risk rating, score details, billable tag, timestamps, and the screening view URL. For profile exports, workbook columns can include identifiers, profile status, profile group IDs, profile group labels, monitoring state, archive state, profile type, flags, assignee, allowlist window, last screened time, timestamps, and the profile view URL. ## Example Use Cases ### 1. Potential Match Export For Analytics Use this pattern when you need to analyze unresolved potential matches across feeds, sources, review queues, or score bands. This example shows: * a potential-match export scoped to unresolved Sanctions, PEP, and News hits * a created-at window for a recent operational period * the live preview table analysts use before locking the snapshot * PII left off for an analytics-oriented workbook Common analytics questions include: * Which feeds are creating the most unresolved volume? * Which sources are producing high-confidence versus borderline matches? * Which profile cohorts need more review capacity? * How did a scoring or source configuration change affect incoming volume? ### 2. Associated Profile Export For Visibility Use this pattern when match-level analytics need profile-level context. When the primary scope targets potential matches, Minerva can add an associated profile stage. The associated stage exports the unique profiles referenced by the locked match snapshot, and you can apply an additional profile query before queueing. This example shows: * a locked potential-match snapshot * an associated profile stage turned on * an additional profile query for active monitored profiles * a profile preview table before workbook submission * PII left off for the associated profile stage Use this for visibility workflows such as reconciling match volume to active customer profiles, reviewing monitored profile exposure, or preparing workload summaries without changing any records. ### 3. Profile Export For Audit Sampling Use this pattern when you need a profile workbook for audit, quality assurance, or internal control evidence. This example shows: * a profile-scoped export for accepted monitored active profiles * profile group filters when the audit sample is tied to a specific segment * a review step with a specific export name and rationale * PII included for the primary profile export stage * snapshot counts and a human-readable scope summary before queueing Use a precise rationale. It appears in export history and helps future reviewers understand why the workbook was created. ## Export History And Workbooks Export history shows queued, processing, completed, partial, and failed export jobs. The history table supports sorting, requester search, status filtering, and workbook availability filtering. Open an export to review: * job status and identifiers * selected, processed, succeeded, failed, and skipped counts * each stage and its progress * exported row snapshots for each stage * workbook availability and download action The workbook is generated asynchronously. A completed or terminal export can still briefly show the workbook as pending until the audit manifest is attached to the job. ## Understanding Scores In Exports Minerva match scores are normalized from **0.00** to **1.00**. * **1.00** means the compared evidence is effectively exact. * Values closer to **1.00** are stronger matches. * Values closer to **0.00** are weaker matches. * In the app preview table, scores are displayed as percentages for readability. When available, export workbooks can also include score details such as field-level criteria match evidence. These labels should be read as: | Label | Score range | Meaning | | ---------------------- | ---------------------------------------------------- | ----------------------------------------------- | | Exact | 0.98 and above | The field is effectively exact. | | Close | 0.85 to below 0.98 | The field is strongly similar, but not exact. | | Loose | 0.75 to below 0.85 | The field is a weaker fuzzy match. | | None | Below 0.75 | The field does not provide meaningful evidence. | The overall match score is not a simple average of the visible labels. The screening engine weighs available evidence such as name, aliases, date of birth, location, identifiers, source data, and feed-specific signals. ## Pre-Resolution vs Post-Resolution Thresholds Exports show the records that passed the current screening and configuration logic. They do not change score thresholds themselves, but they are useful for calibrating those thresholds. Pre-resolution thresholds decide whether raw source candidates are strong enough to enter entity resolution. Minerva has feed-specific pre-resolution thresholds for **Sanctions**, **PEP**, and **News**. Post-resolution thresholds decide whether a resolved candidate remains in the final returned result set after entity resolution clusters related records. How to tune with exports: 1. Export a stable cohort before changing configuration. 2. Group by feed, source, review status, and score band. 3. Raise a feed-specific pre-resolution threshold when weak raw candidates from that feed are creating avoidable volume. 4. Lower a feed-specific pre-resolution threshold when plausible raw source records appear to be missing before entity resolution can evaluate them. 5. Raise the post-resolution threshold when resolved matches are still too broad after clustering. 6. Lower the post-resolution threshold when entity resolution is grouping relevant evidence but the final visible set is too narrow. 7. Re-export the same cohort after the change and compare volume, score distribution, and analyst review outcomes. Tune one workflow and one feed at a time. Changing News thresholds and News geography bias together can make it hard to identify which setting caused a volume or recall shift. ## News Retrieval Controls And Export Analysis News retrieval controls affect adverse-media data before or during Match Scoring. Use exports to compare how changes affect the article pool, score distribution, and analyst outcomes for the same cohort. News geography bias controls geography before news articles reach the Minerva engine. It changes the article pool returned by the News source; the downstream model can only score articles that were retrieved. | Setting | Retrieval behavior | Data bias introduced | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Strict | Uses exact subject-name retrieval and applies city and state terms when they are available. Country-only searches do not add geography. | Biases toward local or regional articles matching supplied city/state context. This reduces common-name noise but can miss national, international, or location-light mentions. | | Broad | Uses a broader city/state/country geography clause when city or state evidence is available. Country is an expansion, not a country-only narrowing term. | Increases recall for regional or country-level coverage while still using subject geography. This can surface broader coverage and may increase common-name noise. | | None | Searches without geography terms. | Applies the least geography bias. This maximizes recall across the News corpus and is most likely to increase unrelated common-name articles. | Use exports to inspect the impact of News geography bias, News name filter, max requested articles, and News location inference by comparing: * total News match volume before and after a setting change * News source names and media URLs for the same profile cohort * match score distribution for News hits * how often News-only matches appear without corroborating Sanctions or PEP evidence * analyst outcomes for common-name subjects versus subjects with strong location evidence * latency-sensitive cohorts where higher article caps or location inference may add processing time Request-level API parameters can override workspace-level News geography and retrieval defaults. Coordinate exports with API consumers when a request explicitly submits match threshold, News geography, News name filter, max requested articles, or News location inference values. ## Best Practices * Start with a narrow query that captures the intended cohort. * Use created-at or last-screened windows for repeatable analytics. * Choose PII only when the workbook purpose requires it. * Add associated profiles when match analysis needs profile context. * Include profile group filters or workbook columns when the analysis is about risk segments, product segments, or other workspace-scoped groups. * Use clear export names and rationales so history remains audit-ready. * Compare exports before and after score-threshold or News retrieval changes. * Download completed workbooks from Export history rather than refreshing the create flow. ## Related Guides * [Screening Guide](/screening-guide) * [Profile Groups Guide](/profile-groups-guide) * [Match Scoring Guide](/match-scoring-guide) * [Bulk Actions Guide](/bulk-actions-guide) * [Repeated Alert Suppression Guide](/alert-suppression-guide) # FAQ Source: https://docs.gominerva.com/faq Frequently asked questions about Minerva results, search behavior, and follow-up steps This FAQ focuses on the result-related questions teams ask most often. If you need help investigating a specific case, contact [support@gominerva.com](mailto:support@gominerva.com). ## Results FAQ ### My results are missing something. Why? There are a few common reasons a result may appear incomplete: * The search was run with limited subject data, such as name only without date of birth, country, employer, or other identifiers. * Different workflows return different levels of depth. Standard screening is designed for fast review, while [Risk Assessment](/minerva-risk-assessment) is the better path for deeper due diligence. * Source coverage can vary by subject, geography, and the quality of available public or structured records. * The result set may need to be reviewed at the alert or source-detail level rather than only from the top-level summary. If a result looks too thin, try adding more identifiers and rerunning the search before deciding that the subject has no relevant history. ### Why do results sometimes look inconsistent? Results can vary when the underlying inputs or context change. Common causes include: * Running searches with different identifiers, spelling, or entity type. * New information appearing in monitored sources over time. * Comparing a quick screening workflow with a deeper investigative workflow. * Reviewing one alert or one source record instead of the full profile history. If two searches appear inconsistent, first compare the subject data used in each search and confirm you are looking at the same workflow and the same subject record. ### My other vendor flagged a person as a PEP, but Minerva did not. Why? This usually comes down to policy differences rather than a simple data gap. Different vendors use different PEP definitions, source sets, lookback periods, relationship rules, and thresholds for keeping a person in active scope. One provider may apply a broader default standard, keep former office-holders in scope for longer, or include relatives and close associates more aggressively. Another may require stronger role, timing, or relationship evidence before classifying a record as an active PEP or RCA result. Minerva uses its own normalized, role-based, risk-sensitive policy rather than treating any upstream source definition as final. That means Minerva may exclude a person if the available evidence does not support a qualifying office, supported RCA relationship, or active lookback treatment under Minerva's standard. For the full definition, inclusion categories, exclusions, and lookback rules, see [PEP Policy](/concepts/pep-policy). ### Why do the results feel over-consolidated? Minerva is designed to reduce noise by grouping related findings into a workflow that is easier to review. In practice, that can sometimes make results feel more consolidated than expected. This usually means: * Similar findings are being grouped under one profile or review path. * The summary view is combining supporting signals that should be reviewed in more detail. * A single subject may have multiple related source hits that are intentionally presented together to speed up analyst review. When this happens, open the underlying profile, alert, or assessment details to inspect the supporting records before making a decision. ### I cannot find my search subject. What should I check? Start with the basics: * Confirm whether the subject should be searched as an individual or an organization. * Try alternate spellings, aliases, abbreviations, or legal entity names. * Add identifiers such as date of birth, country, employer, or related entity data when available. * Check whether the subject was created or reviewed previously under a different profile record. * Use [Risk Assessment](/minerva-risk-assessment) if the case needs broader investigative coverage than a standard screening workflow. If the subject still cannot be found, contact [support@gominerva.com](mailto:support@gominerva.com) with the search inputs you used so the Minerva team can help troubleshoot. ## Working With Results ### What should I do after I find a potential match? Open the profile or alert, review the supporting details, and decide whether the hit should be resolved as a true match, false match, unresolved, or no material change. Then confirm whether the broader profile status also needs to change. ### When should I escalate from screening to risk assessment? Use [Risk Assessment](/minerva-risk-assessment) when the subject needs deeper due diligence, more context, or a documented research package for escalation, onboarding, or compliance review. ### Can I review prior activity for the same subject? Yes. The [Profiles](/minerva-profiles) workflow is designed to help analysts review prior hits, monitoring activity, and earlier decisions so they can determine whether a new result is actually new or just a continuation of an existing case. ## Support ### I still have questions about a specific result. What should I send to support? Include the subject type, the search inputs you used, what you expected to see, and what appears to be missing or inconsistent. That usually gives support enough context to troubleshoot quickly. # Introduction Source: https://docs.gominerva.com/introduction Welcome to the Minerva Knowledge Hub Hero Light Hero Dark ## Getting Started If you're new to Minerva you can get started with the guides below. An introduction to our web application for screening and risk assessments. An introduction to our search, screening, and profile management API's. ## About Minerva **Effortless Risk Screening, Built by AML Experts** Minerva is an AI-powered risk screening platform purpose built for modern compliance teams. Whether you're onboarding new clients, managing ongoing monitoring, or conducting a risk assessment, Minerva can help you identify true risk faster - without all the noise. * Onboard up to 96% of your customers automatically * Reduce false positives by over 75% * Eliminate manual open-source research * Automate monitoring and reporting ### The Minerva Solution Minerva was built to modernize and simplify your AML workflows: * Smarter screening with significantly fewer false positives * Configurable ongoing monitoring to match your needs * Streamlined alert review and reporting * Easy setup and API integration * Built and supported by AML industry experts ### Built for Scale and Compliance Minerva is compliant with global security and privacy standards including: * SOC 2 * ISO 27001 * GDPR * PIPEDA * CCPA * NIST & CIS CSA To learn more please visit our [trust page](https://app.conveyor.com/profile/gominerva). # Match Scoring Guide Source: https://docs.gominerva.com/match-scoring-guide How to configure screening thresholds, candidate scoring weights, matching behavior, News retrieval, entity resolution, and score simulations across Minerva workflows. Match scoring controls how broadly or narrowly Minerva keeps potential screening matches as they move through candidate retrieval, entity resolution, and final result filtering. **Access:** Requires the **Admin** role or above. In the sidebar, go to **Administration** > **Configuration**, then open **Match scoring** under **Screening behaviours**. Use this guide when you need to: * choose between the built-in **Balanced**, **Narrow**, and **Wide** presets * tune one screening channel without changing the other channels * adjust pre-resolution and post-resolution score thresholds * control how much name, alias, date, location, identifier, occupation, gender, email, phone, and notes evidence contribute to candidate scoring * control how missing optional evidence affects the score denominator * tune name, DOB/date, location, and entity-resolution merge behavior * tune News geography, News name filtering, article volume, and News location inference * use the score simulator before saving changes * review, audit, or roll back match scoring deployments **Balanced** is the default Match Scoring configuration for every workspace. It preserves Minerva's legacy scoring posture unless your workspace has explicitly changed the settings. Match scoring changes affect which candidates analysts see. Tune in small increments, use clear change descriptions, and compare review volume, latency, and missed-risk sensitivity before moving further away from Balanced. ## How Match Scoring Works Every screening result passes through three broad stages: 1. **Candidate retrieval**: Minerva gathers source records from the selected feeds. 2. **Pre-resolution scoring**: each source candidate is scored against the searched subject before entity resolution. 3. **Post-resolution scoring**: Minerva clusters likely duplicate source records, scores the resolved candidate, and filters the final returned result set. The Match Scoring configuration controls the second and third stages through: * **Decision thresholds**: feed-specific pre-resolution thresholds and one post-resolution threshold. * **Candidate score weights**: how much each evidence category contributes when it is present. * **Candidate gates**: minimum name and Sanctions/PEP cutoffs that can stop candidates before other evidence helps. * **Name matching behavior**: tolerance for transposed names, initials, phonetics, hyphenation, extra name parts, and organization base/full names. * **DOB/date matching behavior**: soft date falloff, hard date cutoffs, and inferred-date confidence handling. * **Location matching behavior**: default strictness, component cutoff, and whether nationality can satisfy country matching. * **Entity-resolution merge behavior**: merge thresholds and strong organization merge shortcut settings. * **News controls**: geography filter, name filter, article cap, and article-location inference before News match scoring. The configuration is workflow-specific and workspace-scoped. A Calibration workspace can test settings without changing Live until a workspace preset is promoted. | Workflow | What it covers | Typical tuning posture | | ----------------------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | Onboarding | Profile creation and first-pass screening before a customer relationship is active. | Usually stricter because analysts are deciding whether to accept a new profile. | | Ongoing monitoring | Repeated monitoring screens for existing profiles. | Usually conservative because changes can affect recurring alert volume across many profiles. | | Direct API calls | API-driven screening submissions. | Often tuned for partner or reseller integrations. Workspace defaults are preferred, but request-level overrides remain supported. | | Risk assessments | One-off risk-assessment searches in the app. | Often broader because analysts expect to inspect evidence directly in an investigation flow. | ## Channel Tabs And Copying Settings Each workflow is configured on its own tab. The tab navigation stays visible as you scroll so you can see which channel you are changing. Use the channel actions when you need to keep channels aligned: | Action | What it does | When to use it | | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | Copy from another channel | Replaces the current channel with the selected source channel. | Use when onboarding and monitoring should share a posture, or when direct API should start from risk assessment settings before a small adjustment. | | Apply this channel to all | Copies the active channel to every other channel. | Use after validating a complete channel configuration in Calibration and deciding the same settings should apply everywhere. | | Workspace presets | Save a custom draft as a reusable workspace preset, update a workspace preset, or promote it between workspaces. | Use for repeatable operating modes, such as a stricter monitoring preset or a broader investigation preset. | Start from the channel with the clearest calibration evidence. Copy it only after you have compared representative true positives, false positives, and high-volume cases in the simulator or a Calibration workspace. ## Finding Specific Settings The page includes a setting finder and the Minerva command palette also indexes the Match Scoring controls. | Method | How to use it | What happens | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | Page setting finder | Search within the Match Scoring page for terms such as phonetics, DOB, missing evidence, merge threshold, or News article limit. | The page filters or jumps to matching controls so an admin does not need to scan every section. | | Command palette | Open the command palette and search for a setting name or common variant, such as transposition, sound alike, person name cutoff, location strictness, or score simulator. | Minerva opens Match Scoring and highlights the requested control with a brief yellow flash. | Use the command palette when you already know the setting you need. Use the page finder when you are comparing nearby settings inside the same section. ## Understanding Scores Minerva uses normalized match scores from **0.00** to **1.00**. * **1.00** means the compared values are effectively exact matches. * Values closer to **1.00** are stronger matches. * Values closer to **0.00** are weaker matches. * A threshold is the minimum score required to keep the candidate at that stage. In result details and API responses, field-level criteria match labels are interpreted as: | Label | Score range | Meaning | | ---------------------- | ---------------------------------------------------- | ----------------------------------------------------- | | Exact | 0.98 and above | The field is effectively exact. | | Close | 0.85 to below 0.98 | The field is strongly similar, but not exact. | | Loose | 0.75 to below 0.85 | The field is a weaker fuzzy match. | | None | Below 0.75 | The field does not provide meaningful match evidence. | The overall candidate score is not a simple average of the visible field labels. The engine scores the candidate using weighted evidence, candidate gates, missing-evidence behavior, and stage-specific thresholds. ## Built-In Presets Minerva includes three built-in presets. Built-in presets stay fixed, and workspace presets can be created from a custom draft. | Preset | Best for | Main behavior | | ------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | Balanced | Default production posture. | Preserves legacy defaults for customers that do not change match scoring. | | Narrow | Reducing borderline matches and review volume. | Raises thresholds, strengthens identity/date/location evidence, and applies stricter date/location/merge behavior. | | Wide | Calibration reviews, higher-risk cohorts, or investigations where recall matters more than review volume. | Lowers thresholds, broadens News filtering, makes name/date/location matching more tolerant, and lowers merge thresholds. | ### Preset Thresholds Decision thresholds are editable from **0.60** to **1.00**. | Preset | Workflow | Sanctions pre-resolution | PEP pre-resolution | News pre-resolution | Post-resolution | | -------- | ------------------ | -----------------------: | -----------------: | ------------------: | --------------: | | Balanced | Onboarding | 0.85 | 0.85 | 0.85 | 0.85 | | Balanced | Ongoing monitoring | 0.85 | 0.85 | 0.85 | 0.85 | | Balanced | Direct API calls | 0.75 | 0.75 | 0.70 | 0.70 | | Balanced | Risk assessments | 0.75 | 0.75 | 0.70 | 0.70 | | Narrow | Onboarding | 0.90 | 0.90 | 0.90 | 0.90 | | Narrow | Ongoing monitoring | 0.90 | 0.90 | 0.90 | 0.90 | | Narrow | Direct API calls | 0.85 | 0.85 | 0.80 | 0.80 | | Narrow | Risk assessments | 0.85 | 0.85 | 0.80 | 0.80 | | Wide | Onboarding | 0.75 | 0.75 | 0.75 | 0.75 | | Wide | Ongoing monitoring | 0.75 | 0.75 | 0.75 | 0.75 | | Wide | Direct API calls | 0.65 | 0.65 | 0.60 | 0.60 | | Wide | Risk assessments | 0.65 | 0.65 | 0.60 | 0.60 | ### Preset Retrieval And Runtime Summary | Preset | News geography | News name filter | Max requested articles | Location inference | Default location strictness | Merge thresholds | | -------- | -------------- | ---------------- | ---------------------: | ------------------ | --------------------------- | ------------------------------------- | | Balanced | Strict | Strict | 300 | Off | No default | AI-assisted 0.66, exact-evidence 0.66 | | Narrow | Strict | Strict | 200 | Off | City | AI-assisted 0.72, exact-evidence 0.72 | | Wide | Broad | Broad | 600 | Off | No default | AI-assisted 0.60, exact-evidence 0.60 | ## Decision Thresholds Pre-resolution and post-resolution thresholds answer different questions. | Threshold | Stage | What increasing does | What decreasing does | | ----------------------------------------- | ------------------------ | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Sanctions pre-resolution | Before entity resolution | Fewer weak sanctions source records continue into resolution. | More borderline sanctions records can continue and potentially merge with other evidence. | | PEP pre-resolution | Before entity resolution | Fewer weak PEP source records continue into resolution. | More borderline PEP records can continue and potentially merge with other evidence. | | News pre-resolution | Before entity resolution | Fewer weak adverse-media source records continue into resolution. | More borderline News records can continue and potentially merge with other evidence. | | Post-resolution | After entity resolution | Final analyst-visible results become narrower. | Lower-scoring resolved candidates can remain visible. | If weak records are obviously not related to the searched subject, tune the feed-specific pre-resolution threshold first. If records look related before entity resolution but disappear after final scoring, tune the post-resolution threshold. ## Candidate Score Weights Candidate score weights control how much each evidence category contributes when that evidence is present. The dashboard presents the main control once per setting and applies it to both stages. Use **Advanced: split pre/post resolution** only when a channel needs different behavior before and after entity resolution. Most evidence-weight sliders use a customer-facing range of **0.00** to **1.00**. The **Missing evidence penalty** uses **0** to **100**. | Group | Setting | What it affects | Balanced pre | Balanced post | Tuning guidance | | ------------------- | ------------------------------ | --------------------------------------------------------------- | -----------: | ------------: | ------------------------------------------------------------------------------------------------------------------------------------ | | Identity evidence | Primary name | Main searched-subject name compared with the candidate name. | 1.00 | 1.00 | Keep high for most workflows. Lower only when other evidence is highly reliable and names vary substantially. | | Identity evidence | Aliases | Known alternate names on the potential match. | 0.98 | 0.98 | Raise when aliases are reliable and important; lower if alias lists create common-name noise. | | Identity evidence | Identifiers | Government, registration, and other identifier evidence. | 0.05 | 0.05 | Increase when identifiers are normalized and trusted. Keep lower when identifiers are often partial or absent. | | Profile context | Location | Country, state, city, address, and nationality evidence. | 0.10 | 0.75 | Higher values separate similar names by geography. Lower values are broader when locations are incomplete or inconsistent. | | Profile context | DOB / date | Birth date, incorporation date, or formation date. | 0.10 | 0.50 | Higher values make date agreement more decisive. Lower values are broader when dates are often missing, partial, or inferred. | | Profile context | Occupation | Role, job title, or organization relationship evidence. | 0.10 | 0.01 | Increase when role data reliably distinguishes matches. Keep lower when role data is sparse or inconsistently sourced. | | Profile context | Gender | Gender evidence when present on both records. | 0.05 | 0.05 | Use carefully because gender data can be missing or inconsistently reported. | | Supporting evidence | Email | Email address overlap between candidate and match. | 0.05 | 0.05 | Increase when email is a trusted identifier for the workflow. | | Supporting evidence | Phone | Phone number overlap between candidate and match. | 0.05 | 0.05 | Increase when phone data is trusted and not commonly shared or recycled. | | Supporting evidence | Notes | Customer-supplied notes and narrative evidence. | 0.05 | 0.05 | Increase only when notes are consistently structured and reliable. | | Score behavior | Candidate score pass threshold | Internal candidate-score pass threshold for the selected stage. | 0.70 | 0.70 | Higher values filter candidates earlier in the scoring stage. This is separate from public result thresholds. | | Score behavior | Missing evidence penalty | How strongly unavailable optional evidence lowers the score. | 5 | 10 | A value of 0 disables the missing-evidence penalty. Larger values penalize records with unavailable optional evidence more strongly. | **Missing evidence penalty** is safe to turn off. A value of **0** means missing optional fields do not reduce the denominator. For example, if the request includes name and DOB, and the candidate matches the name but has no DOB to compare, the DOB absence does not reduce the score when the missing-evidence penalty is 0. ### Candidate Weight Preset Values | Setting | Balanced pre/post | Narrow pre/post | Wide pre/post | | ------------------------------ | ----------------- | --------------- | ------------- | | Primary name | 1.00 / 1.00 | 1.00 / 1.00 | 1.00 / 1.00 | | Aliases | 0.98 / 0.98 | 0.98 / 0.98 | 0.98 / 0.98 | | Location | 0.10 / 0.75 | 0.25 / 1.00 | 0.05 / 0.50 | | DOB / date | 0.10 / 0.50 | 0.20 / 0.80 | 0.05 / 0.30 | | Occupation | 0.10 / 0.01 | 0.10 / 0.01 | 0.10 / 0.01 | | Gender | 0.05 / 0.05 | 0.05 / 0.05 | 0.05 / 0.05 | | Notes | 0.05 / 0.05 | 0.05 / 0.05 | 0.05 / 0.05 | | Email | 0.05 / 0.05 | 0.05 / 0.05 | 0.05 / 0.05 | | Phone | 0.05 / 0.05 | 0.05 / 0.05 | 0.05 / 0.05 | | Identifiers | 0.05 / 0.05 | 0.05 / 0.05 | 0.05 / 0.05 | | Candidate score pass threshold | 0.70 / 0.70 | 0.78 / 0.80 | 0.60 / 0.60 | | Missing evidence penalty | 5 / 10 | 10 / 20 | 2.5 / 4 | ## Candidate Gates Candidate gates are cutoffs that can stop a candidate before weighted evidence alone determines the score. | Setting | Range | Balanced | Narrow | Wide | What increasing does | | ----------------------------- | ------------ | -------: | -----: | ---: | ------------------------------------------------------------------------------ | | Person name cutoff | 0.00 to 1.00 | 0.50 | 0.60 | 0.35 | Person candidates need stronger name evidence before other signals can help. | | Organization name cutoff | 0.00 to 1.00 | 0.80 | 0.88 | 0.70 | Organization candidates need closer name similarity before continuing. | | Sanctions/PEP cutoff | 0.00 to 1.00 | 0.75 | 0.82 | 0.65 | Sanctions and PEP candidates need stronger total evidence before continuing. | | Sanctions/PEP location weight | 0.00 to 1.00 | 0.05 | 0.10 | 0.02 | Location agreement has more influence for Sanctions and PEP candidate scoring. | Some legacy backend fields remain available for API compatibility but are not shown in the dashboard. Customer-facing configuration should use the settings above. ## Name Matching Behavior Name matching behavior controls how the engine converts compared names into name similarity scores before the name weight is applied. ### Person Names | Setting | Range | Balanced | Narrow | Wide | What it controls | | ------------------------- | ------------ | -------: | -----: | ---: | --------------------------------------------------------------------------------------------------------------- | | Transposition tolerance | 0.00 to 1.00 | 0.9425 | 0.90 | 0.97 | How much name-part transposition affects similarity, such as given and family names appearing in reverse order. | | Initials tolerance | 0.00 to 1.00 | 0.80 | 0.70 | 0.90 | How initials are treated when compared with full given, middle, or family-name parts. | | Extra name penalty | 0.00 to 1.00 | 0.05 | 0.08 | 0.02 | How strongly unmatched extra name parts reduce similarity. | | Text similarity floor | 0.00 to 1.00 | 0.05 | 0.08 | 0.02 | Minimum spelling similarity needed before phonetic matching can help. | | Phonetics tolerance | 0.00 to 1.00 | 0.815 | 0.75 | 0.90 | How much Double Metaphone-style sound-alike similarity can preserve score when spellings differ. | | Length difference weight | 0.00 to 1.00 | 0.70 | 0.80 | 0.50 | How strongly large name-length differences reduce similarity. | | Hyphenated name tolerance | 0.00 to 1.00 | 0.98 | 0.95 | 1.00 | How hyphenated names and expanded variants compare, such as Smith-Jones and Smith Jones. | Use higher tolerance values when the workflow should accept common formatting, transliteration, phonetic, and ordering variation. Use lower tolerance values when name precision matters more and broader recall is creating too many same-name matches. ### Organization Names | Setting | Range | Balanced | Narrow | Wide | What it controls | | ---------------- | ------------ | -------: | -----: | ---: | ------------------------------------------------------------------------------------------------------------- | | Base name weight | 0.00 to 1.00 | 0.75 | 0.80 | 0.65 | How much the normalized base organization name contributes after common suffixes and descriptors are reduced. | | Full name weight | 0.00 to 1.00 | 0.25 | 0.20 | 0.35 | How much the full organization name contributes, including suffixes, descriptors, and trading-name text. | Raise base name weight when legal suffixes, punctuation, and descriptors vary frequently. Raise full name weight when exact full-name agreement should matter more. ## DOB And Date Matching Behavior DOB/date behavior controls how date evidence is scored before the DOB/date weight is applied. | Setting | Range | Balanced | Narrow | Wide | What it controls | | ----------------------------------------- | ------------------- | -------: | ------: | ------: | --------------------------------------------------------------------------------------------------------------- | | Person DOB soft match falloff days | 1 to 36500 days | 730 | 365 | 1825 | How quickly person DOB similarity decays as dates move apart. | | Person DOB hard range cutoff years | 0 to 500 years | 500 | 10 | 500 | Maximum person DOB gap that can receive any date similarity. Beyond this range, date similarity is forced to 0. | | Organization date soft match falloff days | 1 to 36500 days | 3650 | 1825 | 7300 | How quickly organization date similarity decays as incorporation or formation dates move apart. | | Organization date hard range cutoff years | 0 to 500 years | 500 | 20 | 500 | Maximum organization date gap that can receive any date similarity. | | High inferred date confidence | 0.00 to 1.00 | 0.95 | 0.95 | 0.95 | Contribution for high-confidence inferred date evidence when exact date is unavailable. | | Low inferred date confidence | 0.00 to 1.00 | 0.30 | 0.40 | 0.20 | Contribution floor for low-confidence inferred date evidence. | | Normal inferred date range years | 0.10 to 100 years | 2 | 1 | 5 | Year range allowed around normally inferred dates. | | Low confidence date range years | 0.10 to 100 years | 20 | 10 | 30 | Year range allowed around low-confidence inferred dates. | | Apply inferred date confidence weighting | Enabled or disabled | Enabled | Enabled | Enabled | Whether lower-confidence inferred dates contribute less than higher-confidence inferred dates. | The soft falloff is not a pass/fail boundary. It changes the shape of date-score decay for dates within the hard range cutoff. The hard cutoff is the boundary where date similarity becomes 0 before weighting. ## Location Matching Behavior Location matching behavior controls how location evidence is evaluated before the location weight is applied. | Setting | Values / range | Balanced | Narrow | Wide | What it controls | | ----------------------------------- | ---------------------------------------------------- | ---------- | -------- | ---------- | ------------------------------------------------------------------------------------------------------ | | Default location strictness | No default, Country, State / province, City, Address | No default | City | No default | Minimum location level required when a request does not provide its own strictness. | | Strict location cutoff | 0.00 to 1.00 | 0.80 | 0.90 | 0.65 | Minimum component score when strict location matching is active. | | Allow nationality for country match | Enabled or disabled | Enabled | Disabled | Enabled | Whether nationality can satisfy country-level matching when country evidence is missing or incomplete. | Strictness levels are progressive: | Strictness | Matching behavior | | ---------------- | -------------------------------------------------------------------------------------------------------- | | No default | Location details are scored, but no minimum location level is required unless the request sets one. | | Country | Requires country agreement when both sides provide country evidence. Nationality can count when enabled. | | State / province | Requires country and state/province agreement when both sides provide those details. | | City | Requires country, state/province, and city agreement when both sides provide those details. | | Address | Requires all available location levels, including street address, to agree closely enough. | ## Entity-Resolution Merge Behavior Entity resolution combines likely duplicate source records before post-resolution scoring. Merge settings affect candidate clustering, not the final score threshold directly. | Setting | Range | Balanced | Narrow | Wide | What increasing does | | --------------------------------- | ------------------- | -------: | ------: | ------: | ------------------------------------------------------------------------------------------------ | | AI-assisted merge threshold | 0.00 to 1.00 | 0.66 | 0.72 | 0.60 | Automatic AI-assisted merges become stricter, reducing accidental merges. | | Exact-evidence merge threshold | 0.00 to 1.00 | 0.66 | 0.72 | 0.60 | Rule-based or exact-evidence merges require stronger agreement. | | Enable strong organization merges | Enabled or disabled | Enabled | Enabled | Enabled | Allows highly similar organization records to use the strong organization shortcut. | | Strong organization name cutoff | 0.00 to 1.00 | 0.88 | 0.92 | 0.82 | Strong organization shortcut merges require closer organization-name agreement. | | Strong organization date days | 0 to 36500 days | 31 | 14 | 90 | Strong organization shortcut merges tolerate larger incorporation or formation-date differences. | | Strong organization confidence | 0.00 to 1.00 | 1.00 | 1.00 | 0.90 | Shortcut merges are recorded with higher confidence. | Raise merge thresholds when unrelated source records are being combined. Lower them when duplicate records are staying separate and creating repeated analyst review. ## News Controls For Adverse Media Each screening workflow has its own News controls. These settings sit before final match scoring. They change which articles are retrieved, which retrieved articles are admitted for adverse-media analysis, and whether article-linked locations are added before geography scoring. Broadening News retrieval can increase adverse-media volume and processing time. Avoid changing geography bias, name filtering, article caps, and score thresholds all at once unless you are running a controlled calibration pass. | Setting | Values / range | Balanced | Narrow | Wide | Main effect | | --------------------------------- | ------------------- | -------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------- | | News geography filter | Strict, Broad, None | Strict | Strict | Broad | Controls how subject geography is applied by the News retrieval filter before match scoring. | | News name filter | Strict, Broad | Strict | Strict | Broad | Controls how subject names are matched by the News retrieval filter before match scoring. | | Max requested articles | 100 to 750 | 300 | 200 | 600 | Caps how many News article candidates are reviewed for article matching, sentiment scoring, and risk classification. | | Infer article locations from News | Enabled or disabled | Disabled | Disabled | Disabled | Reviews matching News articles for subject-linked geography before News geography scoring. | ### News Geography Filter | Setting | Retrieval behavior | When to use it | | ------- | ----------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | Strict | Uses exact subject-name retrieval and applies city/state terms when available. Country-only searches do not add a geography clause. | Use as the default for common names and high-volume workflows. | | Broad | Uses broader city/state matching with optional country expansion when location evidence is available. | Use when relevant articles often mention only a wider region or country. | | None | Searches without geography terms. | Use for targeted investigations where location evidence is weak or misleading and analysts expect more review volume. | ### News Name Filter | Setting | Matching behavior | When to use it | | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | Strict | Requires exact-name evidence in trusted article fields before News records continue to scoring. | Use for common names, high-volume monitoring, and workflows where precision matters more than recall. | | Broad | Allows bounded token-proximity matches, minor name variation, middle-name expansion, hyphenation differences, and trusted snippet or quote matches. | Use when subjects are often reported with middle names, transliteration variants, entity suffix differences, or reliable partial snippets. | ### Max Requested Articles Raise this value when relevant adverse-media articles may appear later in provider results. Lower it when common-name searches are creating too much latency or when a workflow does not need broad article recall. Higher article caps can add processing time because Minerva may retrieve and review more News candidates. High-volume subjects may take a few additional seconds for each extra 100 articles, especially when retrieval has also been broadened. ### News Location Inference News location inference reviews matching risk-classified News articles and extracts locations that appear tied to the screened subject. Those inferred article locations can then provide more geographic evidence before News match scoring. Turn it on when article text often identifies the subject's relevant city, state, region, country, operations, arrest, investigation, or other subject-linked geography more clearly than the original search request. News location inference uses model-backed article analysis and can add seconds to News searches. Enable it first in Calibration, direct API, or risk-assessment workflows where the extra geographic evidence is worth the added latency before considering it for high-volume monitoring. ## Score Simulator The score simulator lets administrators test the current draft channel settings against an editable example without creating a live search or writing screening results. Use it when you want to answer questions like: * Would this exact-name, missing-DOB candidate still pass if missing evidence is penalized more? * How much does a different city or country reduce the score? * Would a transposed or phonetic name variation pass under Narrow, Balanced, or Wide? * Does the pre-resolution score behave differently from the post-resolution score? * Which setting moved the score enough to pass or fail the selected threshold? ### How To Use The Simulator 1. Select the workflow tab you want to test, such as **Onboarding** or **Direct API calls**. 2. Adjust the draft settings or select a preset. You do not need to save first. 3. Go to **Score simulator**. 4. Choose **Pre-resolution** or **Post-resolution** under **Score using**. 5. Edit the **Screened profile**. Include the subject type, name, date, location, and screening sources that represent the request. 6. Edit the **Potential match record**. Include the candidate name, aliases, date, locations, country, nationality, occupation/role, source lists, and feed hits you want to compare. 7. Click **Run simulation**. 8. Review the resulting score, return/filter state, threshold comparison, and attribute comparison. Run the same example before and after changing one setting. This makes it easier to see whether the score moved because of a threshold, a field weight, missing evidence, name behavior, date behavior, or location behavior. ### Reading Simulation Results | Result area | How to interpret it | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Overall score | The simulated candidate score under the selected workflow and stage. | | Passed / failed | Whether the score meets the selected threshold and gates for that stage. | | Threshold snapshot | The pre-resolution or post-resolution thresholds used for the run. | | Attribute comparison | Field-level comparison scores such as name, aliases, date, city, state, and country. | | Tested fields | The screened-profile and potential-match fields captured in simulator history. | | Simulation history | Recent simulator runs can be reviewed so teams can connect save decisions to examples they tested. Saved changes can link back to the simulations reviewed before deployment. | Simulator results are examples, not production searches. They are best used for calibration and explanation before saving changes or promoting a workspace preset. ## Recommended Tuning Approach Use this sequence when calibrating match scoring: 1. Start from **Balanced** and collect examples of false positives, plausible missed matches, and high-volume review cohorts. 2. Tune one workflow at a time. Onboarding, monitoring, Direct API, and risk assessments often have different tolerance for review volume. 3. Use the simulator to compare representative examples before saving. 4. Adjust feed-specific pre-resolution thresholds when the issue is feed-specific noise. 5. Adjust post-resolution thresholds when entity resolution is grouping candidates correctly but the final result set is too broad or too narrow. 6. Adjust candidate score weights only when the field-level evidence balance is wrong. For example, increase location or DOB/date weights when similar names are passing despite conflicting location or date evidence. 7. Adjust name, DOB/date, and location behavior when the field similarity score itself is too strict or too forgiving. 8. Adjust merge thresholds when entity resolution is over-merging or under-merging source records. 9. Tune one adverse-media retrieval control at a time. Moving geography bias from Strict to Broad or None, turning on Broad name filtering, or raising max requested articles changes the upstream article pool, not only the final score filter. 10. Enable News location inference only where the extra subject-linked geography is worth the added latency. 11. Save a clear change description so history shows why the calibration was deployed. 12. Use history and rollback if the change moves review volume, latency, or recall in the wrong direction. General tuning guidance: * higher public thresholds are stricter and usually reduce analyst-visible matches * lower public thresholds are broader and usually increase recall and review volume * higher evidence weights make that evidence category more influential when present * a higher missing-evidence penalty makes unavailable optional evidence reduce scores more strongly * higher name tolerance settings generally make name variations easier to match, while higher penalties or floors make name matching stricter * lower merge thresholds reduce duplicate resolved candidates but increase over-merge risk * higher article caps and News location inference can increase News search latency * monitoring changes should be made carefully because they can change recurring alert volume across an existing profile population * direct API changes should be coordinated with API consumers, especially if those consumers already submit request-level overrides ## Request-Level Overrides Match scoring is the workspace default. It applies when the screening request does not provide an explicit override. This is the preferred operating model, especially for Direct API customers, because it keeps defaults visible in the dashboard and audit history. Direct API requests can still override settings for partnership, reseller, legacy, or investigation-specific flows. Core screening logic gives request-level values precedence over workspace configuration. For new integrations, use the same customer-facing ranges shown in the dashboard tables. Some backend fields accept broader legacy ranges for backward compatibility, but dashboard-equivalent values are easier to reason about, audit, and compare with simulator runs. | Override type | Preferred request field | Notes | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Canonical runtime object | `global_filters.match_scoring_runtime_config` | Nested object that mirrors the workspace runtime sections: `candidateScoring`, `nameMatching`, `dobMatching`, `locationMatching`, and `entityResolution`. | | Feed pre-resolution threshold | `feed_filters.Sanctions.pre_resolution_match_threshold`, `feed_filters.PEP.pre_resolution_match_threshold`, `feed_filters.News.pre_resolution_match_threshold` | Feed-specific overrides take precedence for that feed. | | Global pre-resolution threshold | `global_filters.pre_resolution_match_threshold` | Applies when a feed-specific threshold is not supplied. | | Post-resolution threshold | `global_filters.post_resolution_match_threshold` | Controls the final returned result set for the request. | | Legacy threshold | `match_threshold` | Legacy alias. It still takes precedence where supported, but new integrations should use stage-specific thresholds. | | Evidence weights | Scalar aliases such as `nameWeight`, `postResolutionNameWeight`, `locationWeight`, `dobWeight`, `identifierWeight` | Aliases normalize into `candidateScoring.preResolutionWeights` and `candidateScoring.postResolutionWeights`. Shared aliases apply to both stages; stage-specific aliases override one stage. | | Missing evidence penalty | `missingEvidencePenalty`, `preResolutionMissingEvidencePenalty`, `postResolutionMissingEvidencePenalty` | Customer-facing 0 to 100 scale. 0 disables the penalty. Larger values penalize missing optional evidence more. | | Name behavior | `transpositionTolerance`, `initialsTolerance`, `extraNamePenalty`, `textSimilarityFloor`, `phoneticsTolerance`, `lengthDifferenceWeight`, `hyphenatedNameTolerance` | Scalar aliases normalize into `nameMatching.person`. | | Organization-name behavior | `baseNameWeight`, `fullNameWeight` | Scalar aliases normalize into `nameMatching.organization`. | | DOB/date behavior | `personDateWindowDays`, `personMaxDateToleranceYears`, `organizationDateWindowDays`, `organizationMaxDateToleranceYears`, inferred-date aliases | Scalar aliases normalize into `dobMatching`. | | Location behavior | `defaultLocationStrictness`, `strictLocationCutoff`, `allowNationalityForCountryMatch` | Scalar aliases normalize into `locationMatching`. | | Merge behavior | `aiAssistedMergeThreshold`, `exactEvidenceMergeThreshold`, `enableStrongOrganizationMerges`, `strongOrganizationNameCutoff`, `strongOrganizationDateDays` | Scalar aliases normalize into `entityResolution`. | | News controls | `news_geography_bias`, `news_name_filter`, `max_requested_articles`, `news_location_inference` | Global or News feed-level values override workspace News settings for the request. | If a request sends both a nested runtime object and scalar aliases, Minerva merges them into one runtime configuration before scoring. Omitted sections fall back to the workspace setting, then to Balanced defaults when no workspace value exists. Example Direct API override: ```json theme={null} { "global_filters": { "post_resolution_match_threshold": 0.78, "match_scoring_runtime_config": { "candidateScoring": { "preResolutionWeights": { "name": 1, "location": 0.25, "time": 0.2, "threshold": 0.78 }, "postResolutionWeights": { "name": 1, "location": 0.85, "time": 0.7, "threshold": 0.8 }, "gates": { "individualNameMinimumContribution": 0.6, "organizationNameMinimumScore": 0.88, "sanctionsPepThresholdOverride": 0.82, "sanctionsPepLocationWeightOverride": 0.1 } }, "nameMatching": { "person": { "positionWeight": 0.9, "initialsWeight": 0.7, "phoneticsWeight": 0.75 } }, "dobMatching": { "individualDateStdevDays": 365, "individualMaxDateToleranceYears": 10 }, "locationMatching": { "defaultStrictness": "city", "strictComponentCutoff": 0.9, "allowCountryMatchFromNationality": false }, "entityResolution": { "mergeDecision": { "modelConfidenceThreshold": 0.72, "ruleBasedConfidenceThreshold": 0.72 } } } }, "feed_filters": { "Sanctions": { "pre_resolution_match_threshold": 0.9 }, "PEP": { "pre_resolution_match_threshold": 0.9 }, "News": { "pre_resolution_match_threshold": 0.85, "news_geography_bias": "strict", "news_name_filter": "strict", "max_requested_articles": 200 } } } ``` Scalar aliases are useful for legacy integrations, but the nested runtime object is easier to audit because related settings stay grouped by scoring behavior. ## Role-Aware Adverse Media Role-aware adverse media is a separate screening configuration that runs after adverse-media articles have been retrieved and analyzed. It helps identify whether a negative article appears to involve the screened subject or is likely only a name mention. Use Match Scoring when you need to tune candidate thresholds, candidate evidence weighting, matching behavior, merge behavior, or News retrieval and article-analysis behavior. Use Role-Aware Adverse Media when you need to show or filter confident article-subject relevance signals after adverse-media analysis has already run. For details, see the [Role-Aware Adverse Media Guide](/role-aware-adverse-media-guide). ## Reviewing And Confirming Changes When you click **Review changes**, Minerva shows a grouped confirmation view before anything is saved. The review dialog shows: * the number of changes and sections affected * the selected preset change, if applicable * each workflow with changed thresholds, weights, gates, matching behavior, merge behavior, and News controls * an optional **Change Description** field * simulator examples linked to the draft, when available Use the change description to capture the reason for the calibration, such as a false-positive review, a model calibration review, a high-risk cohort exception, or a post-launch monitoring adjustment. ## Deployment History And Rollback The Match Scoring page includes a quick **History** preview so you can review recent deployments without leaving the configuration page. Use the preview to: * see the current live deployment first * review prior threshold, weight, matching behavior, merge behavior, and News retrieval changes * preview an older deployment on the main page * open the full audit history page Rollback restores a previous deployment by writing a new history entry. It does not delete prior history. The full history page includes: * **Changed**: when the configuration was saved or rolled back * **Action**: whether the event was an update or rollback * **Summary**: the key scoring changes * **Changed by**: the user who performed the change * **Actions**: rollback entry points for older deployments ## Related Guides * [Screening Guide](/screening-guide) * [Repeated Alert Suppression Guide](/alert-suppression-guide) * [Role-Aware Adverse Media Guide](/role-aware-adverse-media-guide) * [Workspaces Guide](/workspaces-guide) * [Bulk Actions Guide](/bulk-actions-guide) * [Risk Assessment Flow](/risk-assessment-flow) # Minerva App Source: https://docs.gominerva.com/minerva-app Start here for a guided walkthrough of the Minerva web application Use this page as the starting hub for the Minerva UI. The detailed walkthrough is now split into dedicated sections so you can jump directly to reporting, profiles, or risk assessment from the docs navigation. Mockup of the Minerva application walkthrough showing reporting, screening, and risk assessment sections in the left navigation ## Navigate By Workflow Minerva is organized around three primary workflows in the left navigation: 1. Start with **reporting** to understand what needs attention. 2. Move into **profiles** to review onboarding and ongoing monitoring activity. 3. Open **risk assessment** when you need a deeper investigative workflow. Management oversight for screening activity, trends, open risk, and operational metrics. Screening workflows for profile queues, prior hits, alert review, and disposition decisions. Deeper due diligence for higher-risk cases, enhanced research, and exportable reports. ## Recommended First Tutorial Path If you are walking a new user through Minerva, use this sequence: 1. Open the reporting section and explain how leadership monitors program health. 2. Show the profiles queue and how analysts review sanctions, PEP, and adverse media matches. 3. Open a profile that needs escalation and transition into a risk assessment. 4. Show how findings can be captured in a report for downstream review. ## Next Step Choose a section from the cards above or from the left docs navigation to continue the walkthrough. ## User Guides If you want longer step-by-step walkthroughs beyond the quick workflow pages, use these guides: * [Dashboards Guide](/dashboards-guide) * [Screening Guide](/screening-guide) * [Automatic Disposition Guide](/automatic-disposition-guide) * [Risk Assessment Flow](/risk-assessment-flow) * [Agent Risk Assessments Guide](/agent-risk-assessments-guide) # Profiles Source: https://docs.gominerva.com/minerva-profiles Profile review and alert disposition workflows in the Minerva app ## Profiles For Onboarding And Ongoing Monitoring The profiles area is where analysts and compliance teams work through profile-level alerts. * Create or review profiles for customer onboarding. * Monitor ongoing changes across sanctions, PEP, and adverse media. * Investigate potential matches and document true-positive or false-positive decisions. * Use bulk workflows when you need to process larger volumes efficiently. ## Profiles Walkthrough The screening workflow usually follows this sequence: 1. Open **Profiles** to see clients with active alerts or red flags. 2. Select a client profile to review all previous hits and monitoring activity tied to that person or organization. 3. Open an individual alert to inspect the rich supporting information needed to make a decision, including match details, risk indicators, and source coverage. 4. Update the **profile status** based on your organization's risk appetite and internal policy. 5. Update the **alert status** to disposition the hit, such as true match, false match, unresolved, or no material change. ## What You See In Profiles The profiles table gives analysts a working queue for onboarding and ongoing monitoring: Mockup of the screening profiles queue showing clients with profile statuses and alert badges * Profiles with no issues remain visible for tracking and auditability. * Profiles with potential matches show the relevant red-flag categories directly in the table. * Monitoring state and last screened date make it easy to spot recent activity. * Profile status helps teams separate routine cases from escalations that need deeper review. ## Reviewing Previous Hits When you click into a flagged profile, Minerva shows the full history of prior hits for that subject. Mockup of a flagged profile showing previous screening hits and prior match outcomes * Review current and resolved hits in one place. * Compare repeated matches over time. * Use comments and activity history to understand what was decided previously. * Confirm whether a hit is unchanged, newly escalated, or already resolved. ## Reviewing Rich Match Information Selecting a potential match opens the detailed decision workspace. Mockup of the alert decision workspace showing rich match data, risk score, and disposition controls * Compare alternate names, nationality, gender, occupation, and other identifiers. * Review the risk score and the contributing data sources. * See whether the alert is driven by sanctions, PEP, adverse media, or a combination of sources. * Download a PDF report when you need to preserve findings for audit or escalation. The goal of this screen is not only to show that a match exists, but to provide enough context for a defensible decision. Analysts should be able to explain why a hit was accepted, rejected, or escalated. ## Disposition Decisions There are two related decisions in profiles: * **Profile status** reflects the overall customer or entity outcome, such as potential match, in review, escalation, accepted, or rejected. * **Alert status** resolves the specific hit, such as true match, false match, unresolved, or no material change. A useful training approach is to teach new users to make the alert-level decision first, then confirm whether the broader profile status should also change. ## Next Step Continue to [Risk Assessment](/minerva-risk-assessment) when a profile needs deeper due diligence beyond standard screening. # Reporting Source: https://docs.gominerva.com/minerva-reporting Management oversight workflows in the Minerva app ## Reporting For Management Oversight Use the reporting area first when you want a fast read on program performance and current exposure. * Review dashboard summaries for items that require attention. * Check screening analytics for hit rates, profile volumes, and review outcomes. * Use this area to prepare management or audit-friendly oversight views. If you are new to Minerva, begin here before opening individual profiles. It gives you the operational context for the rest of the workflow. ## What Reporting Helps You Answer * Which profiles or alerts currently require attention. * How screening volume and hit rates are trending. * Whether operational review capacity is keeping up with risk activity. * What leadership, compliance, or audit stakeholders need to see at a glance. ## Typical Reporting Walkthrough 1. Open the overview dashboard for a high-level status check. 2. Review screening analytics for volumes, hit rates, and review outcomes. 3. Identify cases or segments that need follow-up in profiles or risk assessment. ## Next Step Continue to [Profiles](/minerva-profiles) to move from management oversight into analyst review workflows. # Risk Assessment Source: https://docs.gominerva.com/minerva-risk-assessment Deeper due diligence workflows in the Minerva app ## Risk Assessment For Deeper Dives Risk assessment is the escalation path when a case needs more than standard screening. * Launch a new assessment for an individual or organization. * Add known identifiers to improve precision, such as date of birth, location, employer, or related entities. * Expand beyond standard screening to deeper due diligence sources. * Generate reports when you need a documented research package. Think of risk assessment as the investigative layer that sits on top of screening. It is best used when an alert needs more context, when onboarding requires enhanced due diligence, or when a relationship changes and a deeper review is warranted. ## Typical Risk Assessment Workflow 1. Choose whether the subject is an individual or an organization. 2. Enter the core identifiers you already know. 3. Add optional fields to narrow results and improve relevance. 4. Select the lists and source types that should be included. 5. Start the assessment and review the returned findings. 6. Export or share a report when you need a documented output. ## When To Use Risk Assessment * A profile alert needs more context before a final decision can be made. * Onboarding requires enhanced due diligence for a higher-risk relationship. * A client, owner, or related party has changed and needs deeper investigation. * Compliance or management needs a report-ready summary of the research. ## Next Step Return to [Minerva App](/minerva-app) to jump to another workflow area. # Profile Custom Fields Guide Source: https://docs.gominerva.com/profile-custom-fields-guide How administrators define organization-wide profile fields and how teams use them in profiles, lists, and batch uploads. Profile custom fields let your organization store information that is specific to your operating model on Minerva profiles. Administrators define the fields once, and profiles can carry values across every workspace in your organization. **Access:** Only administrators can configure definitions. In the sidebar, go to **Administration** > **Configuration** > **Profile Custom Fields**. Other users can view and use permitted fields on profiles and in the profiles list. Use this guide when you need to: * add organization-specific information such as Loan Number or Loan Status * make selected fields available as profile-list columns, filters, and sort options * prepare CSV or XLSX files that include custom profile data * understand required fields, archival, history, and rollback * connect an integration to profile custom fields Definitions belong to your organization and apply across all its workspaces. Profile values still belong to their profiles. Changing workspaces does not create a second set of definitions. ## Key concepts | Concept | What it means | | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | **Definition** | The administrator-managed description of a custom field, including its label, type, required status, priority, and list capabilities. | | **Label** | The customer-facing name shown in Minerva and recognized as a CSV or XLSX column header. Labels can be updated. | | **Field key** | The immutable identifier used by API integrations. For example, the label **Loan Status** might use the key `loan_status`. | | **Priority** | The order in which custom fields appear in profile details and generated templates. | | **Required** | A rule applied when future profiles are created or imported. Existing profiles are not changed automatically. | | **Archived** | A retired definition that cannot accept new values. Archived definitions and prior configuration changes remain available for audit context. | Use field keys, not labels, in API integrations. Labels can change, but keys remain fixed. Record each returned key in the system that sends profile data to Minerva. ## Configure profile custom fields The configuration page lists active and archived definitions. It also shows which fields are required, available for filtering, and displayed in the profiles list. To create a field: 1. Select **Create custom field**. 2. Enter a clear label and, when useful, a description. 3. Confirm the generated field key. Choose a stable key before saving because it cannot be changed later. 4. Select the field type. 5. Leave the field optional unless every future profile must contain a value. 6. Choose whether supported fields can be filtered or shown as a list column. 7. Set the priority, review the change, and save it. Choose labels that make sense to reviewers and upload operators. Use **Loan Number** rather than an internal project code. Descriptions should explain the expected value, not repeat the label. After you edit or archive a definition, the change may take up to about one minute to appear in profile details, profile lists, and other read views. This delay does not change stored profile values. After the read view refreshes, a renamed label appears under its new name and an archived field is omitted. Profile creates, onboarding, and supplied values in updates validate against the latest definition. If Minerva cannot retrieve that definition, it rejects the write rather than saving an unvalidated value. ### Supported types | UI label | Stored value | Guidance | | ------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | **Text** | Text string | Up to 4,000 characters. Suitable for references, names, and short notes. | | **Number** | Integer or decimal | Accepts exact whole numbers through the signed 64-bit range and finite decimal values. Use a text field instead when leading zeroes are significant. | | **Date** | Date string | Use `YYYY-MM-DD`, such as `2026-08-27`. | | **Yes/No** | Boolean | Stores `true` or `false`. | | **Choice** | One configured option | Reviewers see the option label. Integrations send the option's stored value. | | **Structured data** | JSON object or array | Up to 16 KB for the field. It appears on profile details but cannot be a list column, filter, or sort field. | ### Edit Choice options After you save a Choice field, you can add options, change an option's display label, and reorder the options. The stored value for each saved option cannot be changed or removed in this release. Minerva hides or disables removal for saved options; you can still remove a newly added row before saving it. Option values identify data already stored on profiles. Preserving those values keeps historical profile data readable when labels or ordering change. Choose durable stored values, and use display labels for wording that may evolve. If the vocabulary must be replaced, contact [Minerva Support](mailto:support@gominerva.com). You can also archive the field and create a new one, but the new field starts empty and existing profile values are not moved to it. All custom values on one profile have a combined 64 KB limit. Use **Text** for identifier-like values, even when they contain only digits. This preserves leading zeroes and avoids numeric limits in downstream tools. ### Required fields Optional is the default and is safer during rollout. A required field affects future profile creation: * API profile creation and onboarding requests are rejected when the value is missing or `null`. * CSV and XLSX rows fail when the required column or row value is missing or invalid. * Existing profiles and values remain unchanged. * Unrelated profile updates are not rejected only because an older profile lacks the field. Coordinate with your technical team before making a field required. Update API integrations, onboarding flows, and upload processes first. A newly required definition is enforced on the next create or import after the change is active. ### List columns, filtering, and search Administrators can mark up to five non-Structured data fields across the organization as filterable and searchable. A supported definition can also be marked for display in the profiles list. Custom columns appear in the **Columns** picker after organization fields. Each user's column selection is saved as an individual preference. Filtering and sorting follow the selected field's type: * Text supports exact and contains searches. * Number and Date support exact values and ranges. * Yes/No supports either value. * Choice supports configured options. * Structured data does not support columns, filtering, or sorting. ## View profile values When a profile has custom values, Minerva shows the most useful values as chips in the profile header. The complete set appears in the last **Profile details** tab, ordered by definition priority. **Potential matches** remains the default tab. Choice fields show their readable option label. Structured data is formatted for review on the profile page. Fields with no stored value are not shown. ## Include fields in batch uploads Download a current CSV or XLSX template before preparing a batch. Templates are generated from the active definitions and include the recognized custom field labels in priority order. For each custom column: * use the definition label as the header * include every required column and a valid value in every imported row * use a configured Choice option * use `YYYY-MM-DD` for Date values * use valid JSON objects or arrays for Structured data An invalid required value fails that row. An invalid optional value produces a warning, skips only that custom value, and imports the rest of the profile. Review the validation report before confirming the upload. ## Connect an API integration API integrations send an object keyed by immutable field keys and receive a labeled array in profile responses. See the [Profile Custom Fields API guide](/api-reference/profile-custom-fields) for request formats, response examples, validation rules, and compatibility guidance. ## Operating model 1. Define optional fields and confirm labels, types, keys, and Choice options with business and technical owners. 2. Treat saved Choice option values as immutable identifiers in this release. Use display labels for wording changes, and add options when the vocabulary expands. 3. Update API producers and batch templates using the active definitions. 4. Test profile creation, onboarding, updates, reads, filters, and uploads. 5. Make a field required only after every creation path supplies it. 6. Review the five-field filterable limit before enabling another field. 7. Review configuration history after each change. ## Archive, history, and rollback Archive a definition when it should no longer accept new values. Archiving prevents new API writes through that key as soon as the change is active and removes the field from active configuration and generated templates. Stored values remain on profile records for history. An archived field may remain visible in profile read views for up to about one minute, then it is omitted after those views refresh. Do not repurpose an old field by changing its label to a different meaning. Archive it and create a new definition with a new key. This keeps historical data understandable. Configuration history records audited changes. Rollback replays the selected historical snapshot through the current configuration checks, so it does not always succeed. In particular, rollback cannot remove a saved Choice option value. A snapshot that predates a later-added option omits that saved value and is rejected with HTTP 409. Use a forward change that keeps every saved Choice value, such as relabeling, reordering, or adding options, or contact [Minerva Support](mailto:support@gominerva.com). A successful rollback does not reconstruct values that an integration cleared or replace an import file. ## Related guides * [Profiles](/minerva-profiles) * [Profile Groups Guide](/profile-groups-guide) * [Workspaces Guide](/workspaces-guide) * [Profile Custom Fields API guide](/api-reference/profile-custom-fields) * [API Reference](/api-reference/introduction) # Profile Groups Guide Source: https://docs.gominerva.com/profile-groups-guide How to create and use profile groups for dynamic customer segmentation in Screening. Profile groups let your organization segment monitored profiles inside a workspace without creating a new workspace for every operational cohort. Use them for risk, product, geography, diligence, service model, or other internal criteria that can change over time. **Access:** Requires the **Admin** role or above. In the sidebar, go to **Administration** > **Configuration**, then open **Profile segmentation** under **Screening behaviours**. Use this guide when you need to: * create customer-facing segment labels for monitored profiles * assign profiles to one or more segments * understand how profile group priority works * keep retired segments available for audit context * plan profile group use cases for risk segmentation Profile groups are **workspace-scoped**. They help segment profiles inside the selected workspace. Use workspaces for logical operating contexts such as Live and Calibration; use profile groups for dynamic populations inside those contexts. ## Key Concepts | Concept | What it means | | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | Profile group | A workspace-scoped segment that can be assigned to profiles. Examples include Enhanced diligence, Cross-border commercial, or Retail standard monitoring. | | Profile assignment | A profile can belong to more than one group. This is useful when several criteria apply to the same customer. | | Priority | Higher priority wins when a profile belongs to multiple groups and more than one group has monitoring frequency overrides. | | Archived group | A retired segment retained for history and migration context. Archived groups should not be used for new assignments. | | Internal identifier | The system-generated ID used by APIs and integrations. Admins manage labels, descriptions, and priority in the UI. | ## Manage Profile Groups The Profile segmentation page shows the profile groups for the selected workspace. Use the Active, Archived, and All tabs to keep the active working set short while preserving older groups for audit and migration review. Each group has: * **Name**: the label users see in profile views, tables, and configuration history * **Description**: short operational context for the segment * **Rule Priority**: the tie-breaker when a profile belongs to more than one group * **Status**: Active or Archived Use the hover help icons on table labels and form labels for field-specific guidance. ### Create A Profile Group Click **Create profile group**, then enter the label, description, and priority. Minerva generates the internal identifier automatically. Before the group is saved, Minerva opens the standard change review dialog. Add a concise change description that explains why the segment was created or updated. Keep group names stable and business-readable. For example, use **Enhanced diligence** instead of a project code or internal key. ### Archive A Profile Group Archive a group when it should no longer be used for new assignments. Archived groups remain visible in history and can still provide context for older records or migration reviews. Archive instead of renaming a retired group into a new meaning. Reusing an old group for a different population makes past assignments and history harder to audit. ## Assign Groups To Profiles Open a profile and use the profile edit drawer to add or remove group assignments. A profile can belong to multiple groups at the same time. Use multiple groups only when the combination is meaningful. If groups overlap, set priorities so the highest-risk or most specific segment wins for monitoring frequency overrides. ## Programmatic Use Profile groups can also be managed through application API key flows. This is useful when a CRM, core banking platform, case management system, or customer master is the source of truth for segmentation. Typical integration sequence: 1. List profile groups for the workspace and store the returned system-generated IDs. 2. Create, update, restore, or archive groups when your operating model changes. 3. Create or update profiles with the relevant profile group IDs. 4. Remove a group ID from profiles when the profile no longer belongs to that segment. Do not depend on group labels as API identifiers. Labels can be renamed by admins. Use the system-generated profile group ID returned by the API. ## Example Use Cases | Use case | Example group | Why it helps | | ---------------------- | ------------------------------------------- | -------------------------------------------------------------------------- | | Enhanced due diligence | Enhanced diligence | Applies a clear label to customers that require higher-touch review. | | Product exposure | Cross-border commercial | Separates customers with products that create different monitoring needs. | | Lower-risk retail | Retail standard monitoring | Keeps standard populations distinct from elevated-risk groups. | | Private banking | Private wealth | Supports service-model segmentation without creating a separate workspace. | | Migration cleanup | Retired pilot segment | Preserves context for historical assignments while stopping new usage. | ### Example: High, Medium, And Low Risk Segments A common risk-segmentation model is to create three profile groups inside the same workspace and pair them with different [screening frequencies](/screening-frequencies-guide). Higher-risk populations receive the highest allowed cadence, while lower-risk populations can use less frequent monitoring when policy allows. Example when organization caps are Sanctions Daily, PEP Monthly, and News Monthly: | Profile group | Priority | Example population | Sanctions cadence | PEP cadence | News cadence | | ---------------------------- | -------- | ---------------------------------------------------------------------- | ----------------- | ----------- | ------------ | | High risk | 90 | Enhanced diligence, high-risk geography, elevated product exposure | Daily | Monthly | Monthly | | Medium risk | 50 | Standard commercial or retail populations with some risk indicators | Weekly | Monthly | Monthly | | Low risk | 10 | Lower-risk, domestically focused, stable retail or dormant populations | Monthly | Quarterly | Quarterly | Use priority to ensure the higher-risk group wins when a profile belongs to multiple groups. For example, a profile assigned to both **High risk** and **Low risk** should use the High risk monitoring cadence. These are example cadences, not a policy recommendation. Your organization can only choose frequencies that are at or below the configured organization cap for each feed. ## Recommended Operating Model 1. Define groups around durable operating criteria, not temporary investigations. 2. Keep the number of active groups small enough for analysts and admins to understand. 3. Use descriptions to explain inclusion criteria in plain language. 4. Use higher priority for groups that should win when multiple groups apply. 5. Pair profile group design with [Screening Frequencies](/screening-frequencies-guide) if monitoring cadence should differ by segment. 6. Review configuration history after saves and use rollback when a deployment needs to be reverted. ## Related Guides * [Profile Groups Concept](/concepts/profile-groups) * [Screening Frequencies Guide](/screening-frequencies-guide) * [Screening Guide](/screening-guide) * [Workspaces Guide](/workspaces-guide) # Risk Assessment Flow Source: https://docs.gominerva.com/risk-assessment-flow How to create, review, and export a risk assessment The risk assessment workflow is designed for analysts who need to investigate an individual or organization beyond standard screening. Use it when you need a targeted search, ranked potential matches, and an exportable report. ## Before You Begin * Confirm you have access to the **Risk Assessments** section * Gather the subject name before starting * Add date of birth, location, or other identifiers when available to improve match quality ## Step 1. Enter Subject Details Choose whether you are assessing an **Individual** or an **Organization**, then complete the search form. * **Full Name** is required * **Birth Date** and **Location** improve result precision * **Advanced Fields** can be used to narrow the search or validate known information Use the advanced fields only when you have reliable information to add. Precise data helps reduce weak or noisy matches. ## Step 2. Select Assessment Type and Sources Choose the data categories you want to include in the assessment. * In most cases, keep the default assessment type selected * Preset assessment types help you start quickly * **Custom** lets you manually control which lists and sources are included * Source selection should reflect your investigation goal and internal policy Minerva's default assessment type is the recommended option for most searches. Change it only when you have a specific reason to narrow or expand the source set. For more detail on Minerva source coverage, see [Data Feeds](/concepts/data-feeds). ## Step 3. Start the Assessment Select **Start Assessment** to submit the search. Minerva creates the request and returns a ranked list of potential matches based on the information you provided. ## Step 4. Review Potential Matches Review the returned matches in order of **criteria match score**. * Higher scores indicate a closer fit to the search criteria * Review source context before making a decision * Use supporting details to distinguish true matches from false positives ### Understanding the Results Table `Viewing results with match threshold ≥ 83.00%` means the table is currently showing only matches that meet or exceed the active minimum criteria match score. In this example, any result below `83%` is excluded from the list so you can focus on the closest matches first. Use **Filters** to narrow the current result set without rerunning the search. This is useful when you want to focus on a smaller subset of matches based on the current review context. Use **Risk Indicators** to review the types of risk signals associated with a returned match. These indicators help you understand why a profile may require closer review, such as sanctions, watchlist exposure, adverse media, politically exposed person status, or other flagged categories included in the selected sources. Risk indicators are not a final decision on their own. Treat them as review cues that help you prioritize attention and decide whether to open the subject, compare supporting details, or escalate the result internally. Use **No Record Match** when you have reviewed the returned matches and determined that none of them should be treated as a valid match for the subject. This creates a report that documents that conclusion for the current assessment. Use **Combine and view** when multiple returned records appear to refer to the same subject and you want to review them together in a single combined result view. ## Step 5. Handle Empty Results Some assessments return no potential matches at all. In that case, Minerva shows an empty-results state instead of the match table. If no results are found, review which feeds were included in the search and confirm that the subject details were entered correctly. Use **Generate Null Report** when you need a formal record that no relevant matches were found for the selected subject and source set. ## Step 6. View the Subject Select a result row to open the subject view and review the full details for that specific match. Use the subject view to inspect source context, supporting evidence, and the information that contributed to the criteria match score before deciding how to classify the result. Use this page to review the consolidated subject record, including identity details, source-specific evidence, linked entities, and any supporting media or notes that were assembled from the selected result. ## Step 7. Create a Report Once your review is complete, generate a report if you need an audit-ready record or a file to share internally. Reports can be exported as a PDF for documentation and compliance workflows. ## Expected Result At the end of the flow, you should have: * A completed assessment for the subject * A ranked set of reviewed potential matches * An exportable report when documentation is required ## Related Guides * [Minerva App](/minerva-app) * [Agent Risk Assessments Guide](/agent-risk-assessments-guide) * [Data Feeds](/concepts/data-feeds) * [API Introduction](/api-reference/introduction) # Risk Inference Guide Source: https://docs.gominerva.com/risk-inference-guide How Minerva derives PEP, Criminal, and High Risk Industry signals from sourced profile text, and how admins can tune the behavior by screening channel. Risk inference helps Minerva turn relevant, sourced text discovered during a search into explainable screening and Client Risk Rating signals. It complements direct watchlist and configured-list matches; it does not replace them. **Access:** Requires the **Admin** role or above. In the sidebar, go to **Administration** > **Configuration**, then open **Risk Inference** under **Screening behaviours**. Use this guide when you need to: * understand the difference between list-backed and text-derived risk signals * see when PEP, Criminal, and High Risk Industry inference run * tune a workflow that is producing too many false-positive signals * add local terminology or suppress a recurring phrase without writing regular expressions * configure PEP terms separately for tiers 1 through 4 * audit or roll back a Risk Inference change **Keywords** is the default strategy for PEP, Criminal, and High Risk Industry inference in all four screening channels. Risk Inference is workspace-scoped, so a Calibration workspace can be tuned without changing Live. Turning an inference off can reduce analyst-visible signals or Client Risk Rating evidence. Change one channel at a time, record why the change was made, and validate representative true positives as well as false positives. ## What Risk Inference Does Minerva combines structured records with public information discovered while a search is running. **Open Source Intelligence (OSINT)** is sourced public-web information. When Open Source is requested, Minerva retrieves that information in real time and carries sourced occupation, organization, notes, document titles, industry, employer, and other business context into the resolved profile. Risk inference evaluates resolved profile text from all applicable sources. Open Source supplies most newly discovered live-web context, but it is not the only possible source of text. Minerva does not treat every web mention as fact. A keyword finding is an explainable risk signal that analysts should review with the source, identity evidence, and surrounding context. The three inference types have different outcomes: | Inference type | What it looks for | Effect when matched | | ----------------------------------- | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | PEP | Language indicating that an individual holds or held a qualifying public role. | Flags the result as a potential PEP match, can assign the applicable PEP tier, and can contribute to the Inferred PEP Client Risk Rating criterion. | | Criminal | Language indicating criminal events, allegations, charges, or convictions. | Flags the result as a potential Criminal match and can contribute to the Inferred Criminal Client Risk Rating criterion. | | High Risk Industry | Language indicating that a person or organization is connected to a higher-risk business category. | Adds evidence to the High Risk Industry criterion in Client Risk Rating. It does not create a PEP- or Criminal-style potential match. | Direct PEP or Criminal watchlist hits and configured-list results remain separate evidence. Disabling text inference does not disable those sources. A Criminal keyword finding is not a determination of guilt or verified wrongdoing. Analysts should review the identity match, source reliability, date, legal context, and disposition of the matter. When matched, PEP, Criminal, and High Risk Industry can each activate a dynamic Client Risk Rating factor with a default weight of **0.25**, described in the CRR model as a 25-point factor. The final normalized score does not always rise by exactly 25 because other factors, normalization, and overriding criteria can affect the result. ## When Each Inference Runs There are two conditions to keep distinct: 1. the feed gate that allows an inference engine to run 2. the feed combination that supplies the most useful real-time text | Inference type | Engine condition | Feed combination with the clearest effect | Subject types | | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | | PEP | The PEP feed must be requested and the selected channel must use Keywords. | PEP + Open Source. PEP alone is primarily a watchlist/list search; adding Open Source lets Minerva evaluate sourced public-role text found while exploring the web. | Individuals | | Criminal | The Criminal feed must be requested and the selected channel must use Keywords. | Criminal + Open Source. Open Source can contribute sourced notes and document titles that describe criminal events beyond direct Criminal list evidence. | Individuals and organizations | | High Risk Industry | The selected channel must use Keywords and the returned profile must contain applicable business, industry, employer, occupation, or related context. | Ownership + Open Source for organizations is the main intended combination because it supplies business classification and ownership context. This is not a hard feed gate. | Primarily organizations; also employer or occupation context on individuals | If the objective is a list-only PEP check, PEP without Open Source keeps the search focused on watchlist evidence. If the objective includes discovering public-role context from the live web, request PEP and Open Source together. The same logic is used in each configured screening channel: | Channel | What it covers | | ----------------------------------- | ---------------------------------------------------------------------------------------------------------- | | Onboarding | First-pass screening while a new customer or profile is being onboarded. | | Ongoing monitoring | Recurring searches for existing profiles. Changes can affect alert volume across the monitored population. | | Direct API calls | API-driven screening submissions associated with the workspace. | | Risk assessments | Searches run inside risk assessment and due-diligence workflows. | ## Main Configuration Page Each channel has its own PEP, Criminal, and High Risk Industry strategy. You can copy one channel into another or apply the active channel to all four after validating it. ## Strategy Settings Each inference currently supports two strategies: | Strategy | PEP and Criminal effect | High Risk Industry effect | | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | Keywords | Evaluates sourced text using Minerva's built-in term library plus the workspace's additions and suppressions. A finding can flag the potential match and contribute the corresponding inferred CRR factor. | Evaluates applicable business text and can add the High Risk Industry factor and annotation to Client Risk Rating. | | None | Stops text-derived potential-match flagging and the corresponding Inferred PEP or Inferred Criminal CRR contribution for that channel. Direct watchlist and configured-list results remain active. | Stops the High Risk Industry factor and annotation from being added to Client Risk Rating. All other rating criteria remain active. | **None** is not a global screening off switch. It changes only the selected inference type in the selected workspace and channel. ## Default Values New and previously unconfigured workspaces use **Keywords** for all three inference types in all four channels. The built-in library is versioned and displayed in the dashboard with a **Minerva defaults** badge. The tables below summarize the current default categories and representative built-in terms. The terms shown on the configuration page are the authoritative library for the selected workspace. ### PEP Defaults by Tier PEP has one fixed category for each tier. Tier 1 represents the most senior public exposure; tiers 2 through 4 cover progressively more regional, state-linked, and local roles. If text matches more than one tier, Minerva retains the highest applicable exposure level. | PEP tier | Default category | Representative built-in terms | | -------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | 1 | National and international leadership | prime minister, supreme court justice, federal judge, member of parliament, foreign minister, secretary of defense, dictator | | 2 | Regional and senior public office | ambassador of, chief justice, governor of, senator, attorney general, premier of | | 3 | State-owned organizations and agencies | director of a crown corporation, state-owned corporation, federal agency, government corporation | | 4 | Local public office | mayor of, municipal judge, city council, inspector general, special prosecutor | PEP tier categories cannot be added or removed, which keeps the tier model stable. Admins can add or suppress terms within each tier. ### Criminal Defaults The default **Criminal events and allegations** category includes terms such as arrested, incarcerated, convicted, charged with, wanted for, human trafficking, bribery, corruption, organized crime, tax evasion, and terrorism. Admins can add more Criminal categories when a local policy needs separate terminology or review ownership. ### High Risk Industry Defaults High Risk Industry starts with these categories and representative terms: | Default category | Representative built-in terms | | ------------------------------------------------ | ------------------------------------------------------------------------- | | Gambling and gaming | casino, lottery, sports betting, gambling | | Money services, payments, and exchanges | money transfer, remittance agency, currency exchange, cryptocurrency | | Cannabis and recreational drugs | cannabis, marijuana, dispensary | | High-risk lending and offshore finance | payday lending, offshore lending, unsecured loan, unregistered fund | | Precious goods, art, and luxury assets | gold bullion, precious metal, fine art, auction house, yacht | | Vehicle, vessel, and travel dealers | used car, car dealer, travel agency, boat sales, vehicle dealer | | Weapons and defence | arms dealer, firearms dealer, defense contractor | | Charities and non-profits | non-profit, not for profit, fake charity, unregistered charity | | Adult entertainment | adult entertainment, strip club, pornographic website, unlicensed massage | | Property, holding companies, and private capital | real estate, private equity, venture capital, holding company | These categories are broad defaults, not a conclusion that every business in the category is prohibited or suspicious. They provide one input to Client Risk Rating and should be aligned with the organization's own risk methodology. ## Editing Keyword Logic Without Regex The expression builder is designed for compliance users. It stores structured, plain-language rules rather than asking an admin to enter regular expressions. For each category, you can: * review the active Minerva built-in terms * add a local term or phrase * suppress a built-in term or add a false-positive suppression * choose whether **any** or **all** added terms must match * choose how an added term is recognized * restore the Minerva defaults | Match option | Meaning | Example | | --------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | | Contains phrase | Finds the words together in the entered order. | charged with matches “was charged with bribery.” | | Whole word | Finds the complete word, not the same letters embedded in another word. | mayor matches “mayor” but not a longer word that only contains those letters. | | Word starts with | Finds words beginning with the entered text. | fraud can match “fraud” and “fraudulent.” | A suppression is most useful when the same harmless phrase repeatedly causes a known false positive. For example, an admin might suppress `student senator` in PEP tier 2 or `charged with overseeing` in Criminal inference after confirming that those phrases are producing irrelevant hits. ## When to Tune Risk Inference Tune from evidence rather than from one unusual result. | Pattern observed | Recommended first action | | --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | PEP potential matches repeatedly come from a harmless phrase or role that does not meet policy. | Add a narrow suppression in the affected PEP tier and channel. Keep the other tiers unchanged. | | Criminal potential matches repeatedly describe a non-criminal use of a phrase. | Add a phrase-level suppression to the relevant Criminal category. | | A local public role or criminal expression is consistently missed. | Add the narrowest accurate phrase to the applicable tier or category. | | High Risk Industry is raising CRR scores for a business classification your policy does not treat as high risk. | Suppress the specific phrase or tune the affected category. Confirm that other legitimate HRI classifications still contribute to the rating. | | False positives are widespread and cannot be isolated to a small set of terms. | Use None temporarily for the affected inference and channel while the team calibrates. Re-enable Keywords after representative testing. | A safe calibration sequence is: 1. collect a representative set of false positives and known true positives 2. identify the exact category, term, source field, and channel responsible 3. make the smallest term or suppression change that addresses the pattern 4. test the changed channel in a Calibration workspace 5. compare result volume, true-positive retention, and CRR changes against the baseline 6. review the change summary and save a clear reason 7. switch to the Live workspace, deliberately reapply and save the reviewed settings, then monitor the affected workflow Avoid broad suppressions such as a country, common job word, or generic legal term. They can hide unrelated true-positive signals. Prefer the longest phrase that describes the known false-positive context. ## Review, History, and Rollback Risk Inference changes use the same workspace deployment controls as other tenant configuration sections. Before saving, **Review changes** shows: * each affected channel and inference strategy * added, changed, or removed terms and suppressions * category and match-rule changes * an optional change description The history page records who changed the configuration, when it changed, the affected sections, and the saved description. Rollback restores a prior snapshot by creating a new history entry; it does not erase the audit trail. ## Related Guides * [PEP Policy](/concepts/pep-policy) * [Data Feeds](/concepts/data-feeds) * [Risk Rating](/concepts/risk-rating) * [Screening Guide](/screening-guide) * [Match Scoring Guide](/match-scoring-guide) * [Workspaces Guide](/workspaces-guide) * [Risk Assessment Flow](/risk-assessment-flow) # Role-Aware Adverse Media Guide Source: https://docs.gominerva.com/role-aware-adverse-media-guide How to configure role-aware adverse media labels and filtering across Minerva screening workflows. Role-aware adverse media helps Minerva distinguish adverse media articles that appear to involve the screened subject from articles that only mention the same or a similar name. **Access:** Requires the **Admin** role or above. In the sidebar, go to **Administration** > **Configuration** > **Adverse Media**, then open **Role-Aware Adverse Media**. Use this guide when you need to: * understand what role-aware adverse media controls * choose between Hint Mode and Decision Mode * tune confidence thresholds by workflow * understand the visible article labels and API metadata * review, audit, or roll back role-aware changes Role-aware adverse media is workspace-scoped. Use a Calibration workspace to review labels and thresholds before applying stricter behavior in Live. Decision Mode can change which adverse-media potential matches analysts see. Start in Hint Mode when calibrating, review examples, and save clear change descriptions before moving to automatic filtering. ## How Role-Aware Adverse Media Works Role-aware adverse media runs after Minerva has retrieved and analyzed news or open-source articles. It does not broaden article retrieval on its own. At a high level, Minerva: 1. retrieves articles from the selected adverse media sources 2. identifies negative or risky articles through adverse-media analysis 3. checks whether each qualifying article appears related to the screened subject 4. either shows the result as an article label or uses it to filter unrelated adverse-media hits, depending on the workflow configuration Role-aware adverse media complements match scoring. Match scoring controls candidate thresholds; role-aware adverse media controls confident article-subject relevance signals after article analysis. ## Main Configuration Page The Role-Aware Adverse Media page is organized by workflow, so each screening path can have its own posture. Minerva currently separates: | Workflow | What it covers | | ----------------------------------- | ------------------------------------------------------------------------------------ | | Onboarding | Screening performed during customer or profile onboarding. | | Ongoing monitoring | Background monitoring checks for existing profiles. | | Direct API calls | API-driven screening submissions. | | Risk assessments | Risk assessment searches, including adverse-media-only and combined source searches. | ## Controls ### Enable Role-Aware Insights Turn on **Enable role-aware insights** when you want Minerva to run role-aware checks for a workflow. When this setting is off, role-aware thresholds do not affect that workflow. ### Automatic Role-Based Filtering After role-aware insights are enabled, choose how Minerva should use the output: | Mode | Behavior | When to use it | | ------------------------------ | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- | | Hint Mode | Shows qualifying role-aware article labels while keeping adverse media alerts unchanged. | Use first when calibrating or when analysts should see the model output as review context. | | Decision Mode | Shows qualifying labels and filters unrelated adverse-media hits above the confidence threshold. | Use after reviewing examples and deciding that confident non-subject articles should not create alerts. | ### Role-Aware Confidence Threshold The **Role-aware confidence threshold** controls when labels and Decision Mode removals apply. * range: **0.00** to **1.00** * default: **0.50** * higher values are stricter and require stronger model confidence * lower values are broader and can show or filter more articles ## Analyst-Facing Labels When role-aware output is visible, Minerva can show these adverse-media article labels: | Label | Meaning | | --------------------------------------- | ------------------------------------------------------------------- | | Potentially implicated | The article appears related to the screened subject. | | Secondary mention | This person appears in the article, but not as the primary subject. | These labels are review aids. They do not replace analyst review of the article, source context, and full screening result. ## API and Export Output When role-aware metadata is present, returned adverse-media articles can include a `role_aware_prediction` object. ```json theme={null} { "role_aware_prediction": { "label": "non-suspect", "related_to_subject": false, "score": 0.91, "suspect_prob": 0.09, "non_suspect_prob": 0.91 } } ``` The `label` is `suspect` or `non-suspect`. The `related_to_subject` field is the boolean form of that label, and `score` is the confidence score for the selected label. Role-aware metadata is optional. It appears only when the workflow is configured to run role-aware checks, the article qualifies for analysis, and the model confidence meets the configured threshold. ## Relationship to Match Scoring News and adverse-media tuning has three related layers: | Layer | What it controls | | ----------------------------------------- | --------------------------------------------------------------------------------------- | | News retrieval controls | Which articles are retrieved, admitted, capped, or location-enriched before scoring. | | Match scoring | Which source candidates survive pre-resolution and post-resolution thresholds. | | Role-aware adverse media | Whether adverse articles appear to involve the screened subject or only mention a name. | For threshold and News retrieval details, see the [Match Scoring Guide](/match-scoring-guide). ## Recommended Tuning Approach Use this sequence when calibrating role-aware adverse media: 1. Start in **Hint Mode** for the workflow you want to evaluate. 2. Review common-name and article-mention false positives. 3. Compare role-aware labels against the underlying articles and analyst decisions. 4. Raise the threshold if labels feel too uncertain. 5. Lower the threshold only after reviewing representative examples. 6. Move to **Decision Mode** when confident non-subject articles should stop contributing to adverse-media alerts. 7. Tune one workflow at a time and save a clear change description. ## Reviewing and Confirming Changes When you click **Review changes**, Minerva shows a grouped confirmation view before anything is saved. The review dialog shows: * the number of changes and sections affected * each workflow with changed role-aware insight settings * each changed Hint Mode or Decision Mode setting * each changed confidence threshold * an optional **Change Description** field Use the change description to capture the reason for the calibration, such as a false-positive review, a Calibration-to-Live rollout, or a post-launch monitoring adjustment. ## Deployment History and Rollback The Role-Aware Adverse Media page includes history and rollback tools so you can audit prior deployments and restore an older configuration when needed. The full history page includes: * **Changed**: when the configuration was saved or rolled back * **Action**: whether the event was an update or rollback * **Summary**: the key role-aware changes * **Changed by**: the user who performed the change * **Actions**: rollback entry points for older deployments Rollback restores a previous deployment by writing a new history entry. It does not delete prior history. ## Related Guides * [Adverse Media](/concepts/adverse-media) * [Adverse Media Categories](/adverse-media-categories) * [Match Scoring Guide](/match-scoring-guide) * [Screening Guide](/screening-guide) * [Repeated Alert Suppression Guide](/alert-suppression-guide) * [Workspaces Guide](/workspaces-guide) * [Risk Assessment Flow](/risk-assessment-flow) # Screening Frequencies Guide Source: https://docs.gominerva.com/screening-frequencies-guide How to configure ongoing monitoring cadence caps, workspace defaults, and profile group overrides. Screening frequencies control how often ongoing monitoring runs for Sanctions, PEP, and News on monitored profiles. Use this configuration when different profile populations need different monitoring cadences while staying within organization-level limits. **Access:** Requires the **Admin** role or above. In the sidebar, go to **Administration** > **Configuration**, then open **Screening frequencies** under **Screening behaviours**. Use this guide when you need to: * review the maximum allowed monitoring cadence for each feed * set workspace-level default cadences * apply profile group-specific monitoring overrides * understand how group priority affects monitoring * review, audit, or roll back frequency changes Screening frequencies apply to **ongoing monitoring** for profiles. They do not change one-off searches, manual API requests, or initial profile creation behavior unless those workflows explicitly use ongoing monitoring. ## How Cadence Resolution Works Minerva resolves monitoring frequencies in this order: 1. **Organization Caps** define the highest allowed frequency for each feed across all workspaces and profile groups. 2. **Workspace settings** define the default cadence for profiles in the selected workspace. 3. **Profile group settings** can override the workspace cadence for profiles assigned to that group. 4. If a profile belongs to multiple groups, the highest-priority active group wins. 5. If the winning group does not set a feed override, that feed inherits the workspace setting. A workspace or profile group cannot be configured to screen more frequently than the organization cap for that feed. ## Main Configuration Page The Screening frequencies page has three sections: Organization Caps, Workspace settings, and Profile group settings. ### Organization Caps Organization Caps are the highest frequencies allowed across all workspaces and profile groups. If your organization does not have explicit caps configured, Minerva uses these defaults: | Feed | Default cap | | -------------------------- | ----------- | | Sanctions | Daily | | PEP | Monthly | | News | Monthly | These caps are shown for context on the page. They protect tenant-level controls by preventing a workspace or group from silently increasing monitoring beyond what the organization allows. ### Workspace Settings Workspace settings are the default monitoring cadences for profiles in the selected workspace when no profile group override applies. Use workspace settings for the baseline population. For example, Live might use Daily Sanctions and Monthly PEP/News, while Calibration can test less frequent monitoring before the settings are promoted or copied into production workflows. ### Profile Group Settings Profile group settings override workspace defaults for a selected active group. This lets you run tighter or looser monitoring for a customer segment without changing every profile in the workspace. Use the profile group selector to switch between groups. The selector keeps long group lists out of the page layout while still allowing each group to carry its own cadence settings. ## Cadence Options Available cadence options depend on the feed and the organization cap. | Cadence | Meaning | | ----------------------------- | --------------------------------------------------------------------------- | | Daily | Monitor once per day when the profile is due. | | Deltas | Monitor on supported Sanctions source deltas. Available only for Sanctions. | | Weekly | Monitor weekly when the profile is due. | | Monthly | Monitor monthly when the profile is due. | | Quarterly | Monitor quarterly when the profile is due. | | Semiannually | Monitor twice per year when the profile is due. | | Annually | Monitor once per year when the profile is due. | | Never | Do not run that feed through scheduled ongoing monitoring. | The UI hides or disables options that would exceed the organization cap. For example, if the PEP cap is Monthly, PEP cannot be set to Daily or Weekly at the workspace or profile group level. ## Example Use Cases | Use case | Workspace default | Profile group override | | -------------------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- | | Enhanced due diligence | Sanctions Daily, PEP Monthly, News Monthly | Keep the Enhanced diligence group at the maximum allowed cadence. | | Lower-risk retail | Sanctions Daily, PEP Monthly, News Monthly | Set Retail standard monitoring to Sanctions Weekly, PEP Quarterly, News Quarterly if policy allows. | | Sanctions delta monitoring | Sanctions Daily | Set a targeted Sanctions group to Deltas when source-delta processing is the intended operating model. | | Product-driven review | Standard workspace defaults | Give Cross-border commercial a tighter Sanctions cadence than the baseline retail population. | | Exit or dormant review | Standard workspace defaults | Set selected feeds to Never only when your monitoring policy allows a dormant or exit population to stop scheduled checks. | Start with workspace defaults, then add group overrides only for segments that have a clear policy reason. Too many overrides make monitoring harder to audit. ## Reviewing And Confirming Changes When you change workspace or profile group frequencies, Minerva shows the standard pending changes bar. Click **Review changes** to inspect the exact deltas before saving. The review dialog summarizes: * workspace cadence changes * profile group cadence changes * which feeds changed * the prior and new cadence for each changed feed * an optional change description for audit history Use change descriptions to capture the policy reason, such as a risk segmentation rollout, review-volume adjustment, source-delta pilot, or calibration result. ## History And Rollback The page includes the standard configuration history drawer and history page. Use history to: * review who changed monitoring cadences and when * compare prior and current frequency deployments * preview a historical deployment before rollback * record rollback as a new audited change Rollback restores the saved workspace and profile group frequency snapshot when the referenced groups still exist. ## Related Guides * [Profile Groups Guide](/profile-groups-guide) * [Profile Groups Concept](/concepts/profile-groups) * [Screening Guide](/screening-guide) * [Workspaces Guide](/workspaces-guide) # Screening Guide Source: https://docs.gominerva.com/screening-guide How to use Screening The Screening section is used to manage monitored subjects, review potential matches, and document match decisions as part of your ongoing compliance workflow. ## When to Use This Guide Use this guide when you need to: * create or review screened profiles * investigate potential matches * mark matches as true or false * manage ongoing monitoring activity ## Before You Begin * Confirm you have access to the **Screening** section * Make sure you know which subject you want to review or add * Gather any supporting details that can help with match decisions, such as date of birth, geography, or organization ## Main Areas ### Profiles Profiles represent the individuals or organizations your team is monitoring. Use the profile list to: * review screening status * search for a profile * open an existing subject for more detail * review profile group labels when your organization uses dynamic segmentation * manage the set of monitored subjects in your program `Last Screened` shows the most recent time Minerva completed screening for that profile. Use it to understand how current the profile’s latest screening results are. If your organization uses [Profile Groups](/profile-groups-guide), profile group labels help separate populations such as enhanced diligence, product exposure, or standard retail monitoring without creating separate workspaces. ### Create Profile Use **Create profile** when you need to add a new monitored subject to Screening. When you select **Create profile**, Minerva lets you choose between: * **Single profile**: use this when you are adding one subject manually in the UI * **Multiple profiles**: use this when you are uploading a CSV to create many profiles at once #### Single Profile Choose **Single profile** when you have one individual or organization to add. Use this path to: * enter subject details directly in the UI * create a profile immediately without preparing a file * add one-off monitoring records as needed #### Multiple Profiles Choose **Multiple profiles** when you need to upload a batch of new subjects. The batch flow is a two-step process: 1. upload a CSV file 2. preview the mapped data and confirm the upload Use this path to: * onboard many monitored subjects at once * validate the uploaded file before submission * move to upload history after confirmation ### Potential Matches Profiles with risk can produce potential matches that require analyst review. Use potential match review to: * compare subject details against returned results * inspect source context and supporting evidence * evaluate risk indicators * classify results according to your internal process ### Single Potential Match View Open a potential match when you need to inspect the returned record in detail before making a decision. Use the single-match view to: * review identity details and source lineage * inspect sanctions, PEP, and adverse media sections * evaluate the risk score and supporting indicators * decide whether the record is your subject #### Change Match Status Use the **Match Status** control on the right side of the page to classify the current potential match. The available match statuses are: * **Unresolved**: the match still needs review * **True Match**: the returned record is your subject * **False Match**: the returned record is not your subject * **No Material Change**: the match exists, but there is no material change to act on * **Reopened**: the match has been reopened for additional review In the current UI, **True Match** and **False Match** prompt for confirmation before the status is applied. #### Change Profile Status Use the **Profile Status** control in the profile header to update the overall workflow state of the monitored subject. The selectable profile statuses are: * **Potential match**: the profile still has unresolved screening results * **In review**: the profile is actively being reviewed by an analyst * **Escalation**: the profile needs additional review or approval * **Accepted**: the review outcome has been accepted * **Rejected**: the review outcome has been rejected Use **Match Status** for the specific result you are reviewing. Use **Profile Status** for the overall state of the full monitored profile. #### Risk Criteria Use the **Risk Criteria** section to understand which factors are contributing to the match risk score. Risk criteria help you see: * which screening categories contributed to the score * which risk factors were triggered for the record * where to focus your review first Use this section as supporting context during adjudication. It helps explain why the match appears risky, but it does not replace analyst review of the underlying sanctions, PEP, adverse media, and profile details. ### Comments Use the comments tab to capture analyst context that should stay attached to the profile. Use comments to: * document why a profile remains in review * record supporting facts from your investigation * leave context for another analyst or approver ### Activity Use the activity tab to review the timeline of screening and profile actions. Use activity to: * see when monitoring runs completed * track status changes on the profile * understand what actions were taken and when ### Bulk Actions Use **Bulk Actions** when the same screening update needs to be applied across a large working set. Common bulk-action workflows include: * closing many potential matches in one queued job * archiving a resolved cohort of profiles * turning monitoring on or off for many profiles * adding the same operational comment to many profiles Bulk Actions is designed for large asynchronous jobs and is intended for Admin- or Owner-led operational changes. For step-by-step bulk-action workflows, follow the [Bulk Actions Guide](/bulk-actions-guide). ## How to Work With Screening * Start at the **Profiles** view when you need to find a subject or understand their current monitoring status. * Use **Create profile** when you need to add a new monitored subject, either one at a time or in bulk by CSV. * Open **Potential Matches** when a screened subject has returned results that require analyst review and disposition. * Use the **single potential match view** when you need to inspect source-level detail and make a match decision with more confidence. * Use **Comments** when you need to preserve analyst reasoning on the profile itself. * Use **Activity** when you need the chronological history of screening events and profile updates. * Use **Bulk Actions** when many matches or profiles need the same change and you want Minerva to process that change asynchronously with audit history. ## Expected Result At the end of this workflow, you should have: * a clear view of the monitored subject * reviewed potential matches with supporting context * documented decisions that support your screening and monitoring process ## Related Guides * [Minerva App](/minerva-app) * [Profile Groups Guide](/profile-groups-guide) * [Screening Frequencies Guide](/screening-frequencies-guide) * [Bulk Actions Guide](/bulk-actions-guide) * [Dashboards Guide](/dashboards-guide) * [Risk Assessment Flow](/risk-assessment-flow) # Training Videos Source: https://docs.gominerva.com/training-videos Watch Minerva training videos and walkthroughs from one place Use this page as the video library for the Minerva Knowledge Hub. Add new training videos here as they become available so users have a single place to find walkthroughs. ## Video Library This section organizes recorded Minerva training content for onboarding, feature walkthroughs, and refresher sessions. ## Browse Videos Use the links below to jump directly to a training recording: Learn how to create a profile for screening. Review screening results and alert workflows. Walk through the risk assessment workflow. ## Core Product Walkthroughs ### Creating a Profile for Screening If the embedded player does not load correctly, watch Creating a Profile for Screening on VEED.