Introduction

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.
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 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, which also still accepts the legacy `X-Api-Key` header for existing integrations.
`Authorization: Bearer`	Hosted MCP personal access token	The Minerva MCP server only. Application API keys are never accepted there.

API Overview

The Minerva API is organized around two key capabilities:

Profile Management
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.<field>`, `<profile_field>.match_score`, `<profile_field>.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[]`, `<profile_field>.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.

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

checklist.screen.Sanctions: true is the direct risk indicator.
score: 0.94 says the candidate is a strong overall criteria match.
checklist.hits.Sanctions identifies the list that triggered the flag.
checklist.hits_info[] shows that the name is close and the reported date is exact.
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 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:

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"]
  }'

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();

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:

{
  "status": 200,
  "jobid": "<jobId>",
  "searchId": "<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:

curl -X POST https://api.gominerva.com/v1/reports \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "searchResultId": "<searchId>",
    "index": 0
  }'

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();

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:

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

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"]
  }'

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();

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:

{
  "status": 200,
  "message": "Requests successfully submitted",
  "id": "<jobId>"
}

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:

curl -X POST https://api.gominerva.com/v1/searchStatus \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "<jobId>"
  }'

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();

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:

{
  "status": 200,
  "response": "complete",
  "results": [
    {
      "request": { "name": "Jane Doe" },
      "searchId": "<requestId>_0",
      "results": [
        {
          "name": {
            "value": "Jane Doe",
            "match_score": 1.0,
            "criteria_match_level": "exact"
          },
          "score": 1.0
        }
      ]
    },
    {
      "request": { "name": "Acme Corp" },
      "searchId": "<requestId>_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:

curl -X POST https://api.gominerva.com/v1/reports \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "searchResultId": "<requestId>_0",
    "index": 0
  }'

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();

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:

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

API Documentation

Screening - Endpoints

Admin Actions - Endpoints

Profiles - Endpoints

Agent Risk Assessments - Endpoints

Getting Access

Authentication Schemes

API Overview

1. Profile Management & Monitoring

2. Real-Time Risk Assessment

Interpreting Screening Results

High-Level Sanctions Example

Recommended Report Generation Flow

Single Search Flow

Batch Search Flow

Summary

​Getting Access

​Authentication Schemes

​API Overview

​1. Profile Management & Monitoring

​2. Real-Time Risk Assessment

​Interpreting Screening Results

​High-Level Sanctions Example

​Recommended Report Generation Flow

​Single Search Flow

​Batch Search Flow

​Summary

Getting Access

Authentication Schemes

API Overview

1. Profile Management & Monitoring

2. Real-Time Risk Assessment

Interpreting Screening Results

High-Level Sanctions Example

Recommended Report Generation Flow

Single Search Flow

Batch Search Flow

Summary