Introduction

The Minerva API lets financial institutions and other regulated organizations automate parts of their anti-money laundering (AML) compliance workflows. It uses deep learning models to consolidate information from more than 250,000 global sources, covering nearly 1 billion individuals and entities and over 4.5 billion data points, and returns structured results for 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

API access is managed from the Minerva dashboard:

Create and manage API keys under Administration > Developers. That page requires the Developer role or above. See API Keys for the full walkthrough, and the SAML SSO and SCIM Guide for how roles are assigned.
Create separate live and dev applications so each integration has its own key lifecycle, usage history, and owner context.
Contact support@gominerva.com for additional access or integration requests.
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

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.

What the API covers

The API covers three areas: profile management, identity verification, and real-time risk assessment. Most integrations use more than one.

Profile management and monitoring

Screen and register a customer in a single step during onboarding.
Keep customer profiles current and synchronize data between your systems and Minerva.
Monitor profiles for changes in risk status or new matches.
Use the API and webhooks to drive investigation workflows and review queues, and to keep internal systems in sync. Configure webhook destinations from the Developers page (API Keys).

Identity verification

Create identity verification (IDV) sessions for your customers: your backend starts the session and delivers the verification flow, and the outcome lands on the customer’s profile and in webhooks. The IDV Integration Guide walks through the full flow, from profile creation to review outcomes.

Real-time risk assessment

Minerva screens individuals and entities against global watchlists (sanctions, PEPs, criminal and terror lists) and adverse media mentions, and enriches each result with supporting evidence and confidence scoring. The Data Feeds page lists the feeds you can request.

Real-time screening: screen one profile synchronously and read the result from the response.
Batch screening: submit large batches of profiles for parallel asynchronous processing, which supports high-volume operations.
Reports: generate audit-ready summaries of search results and profile data for documentation, audits, and compliance or regulatory filings.

Reading a screening response

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. Answer three separate questions when you map 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, which 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.

Compare all available identifiers and source evidence before you disposition the candidate as a true positive, false positive, or unresolved.

The Screening Integration Guide covers the full response hierarchy, the Sanctions, PEP, and News mappings, score interpretation, and the recommended analyst review order.

Screening and report flows

Use POST /v1/reports with a searchResultId from a previous search. The flow is the same for one profile and for a batch: run the search, take the searchId from its response, then pass that value as searchResultId.

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

Next steps

API Keys: create an application key and configure webhooks.
Screening Integration Guide: the full response reference, field mapping, and recommended analyst review order.
Search History: retrieve past screening requests and their match results for audit and reconciliation.

API Documentation

Screening - Endpoints

Admin Actions - Endpoints

Profiles - Endpoints

Agent Risk Assessments - Endpoints

Identity Verification - Endpoints

Getting access

Authentication

What the API covers

Profile management and monitoring

Identity verification

Real-time risk assessment

Reading a screening response

High-level sanctions example

Screening and report flows

Single search flow

Batch search flow

Next steps

​Getting access

​Authentication

​What the API covers

​Profile management and monitoring

​Identity verification

​Real-time risk assessment

​Reading a screening response

​High-level sanctions example

​Screening and report flows

​Single search flow

​Batch search flow

​Next steps

Getting access

Authentication

What the API covers

Profile management and monitoring

Identity verification

Real-time risk assessment

Reading a screening response

High-level sanctions example

Screening and report flows

Single search flow

Batch search flow

Next steps