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.
API keys are not currently scoped by per-key RBAC permissions.

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`	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.”

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

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

​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

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