> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gominerva.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Warning>
  ⚠️ **URL Migration Notice:** Legacy `*.minervaai.io` URLs are deprecated. Use
  the `*.gominerva.com` URLs shown throughout this API reference for all new
  integrations.
</Warning>

## Getting Access

Access to the Minerva API is managed through the Minerva dashboard:

* API keys are created and managed from <strong>Administration</strong> > <strong>Developers</strong>. This page requires the <strong>Developer</strong> 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).
* API keys are not currently scoped by per-key RBAC permissions.

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

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

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

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

## Recommended Report Generation Flow

Use `POST /v1/reports` with a `searchResultId` from a previous search.

<Info>
  The abbreviated responses below only show the fields you need to carry from
  one step to the next: `jobid`, `searchId`, `searchResultId`, `index`, and
  `reports`.
</Info>

### Single Search Flow

**Step 1: Run `POST /v1/search-sync`**

Request:

<CodeGroup>
  ```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()
  ```
</CodeGroup>

Response:

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

<Tip>
  Save `searchId`. For `search-sync`, this value becomes `searchResultId` in the
  report-generation request.
</Tip>

**Step 2: Run `POST /v1/reports` with that `searchId`**

Request:

<CodeGroup>
  ```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": "<searchId>",
      "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()
  ```
</CodeGroup>

Response:

```json theme={null}
{
  "status": 200,
  "response": "Reports generated",
  "reports": ["https://storage.googleapis.com/.../Minerva-Report.pdf"]
}
```

<Note>
  `index` selects the ranked match from the prior search response: `0` for the
  top match, `1` for the second match, and so on.
</Note>

### Batch Search Flow

**Step 1: Run `POST /v1/search`**

Request:

<CodeGroup>
  ```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()
  ```
</CodeGroup>

Response:

```json theme={null}
{
  "status": 200,
  "message": "Requests successfully submitted",
  "id": "<jobId>"
}
```

<Tip>
  Save `id` from this response. This is the batch `jobid` you use to read the
  completed results.
</Tip>

**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:

<CodeGroup>
  ```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": "<jobId>"
    }'
  ```

  ```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()
  ```
</CodeGroup>

Response:

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

<Tip>
  Each `results[n].searchId` is entity-scoped. Pick the `searchId` for the
  subject you want to report on, then pass that value as `searchResultId`.
</Tip>

**Step 3: Run `POST /v1/reports` with the batch result `searchId`**

Request:

<CodeGroup>
  ```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": "<requestId>_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()
  ```
</CodeGroup>

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