curl --request GET \
--url https://api.gominerva.com/v2/search/matches \
--header 'x-api-key: <api-key>'import requests
url = "https://api.gominerva.com/v2/search/matches"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};
fetch('https://api.gominerva.com/v2/search/matches', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.gominerva.com/v2/search/matches",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.gominerva.com/v2/search/matches"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("x-api-key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.gominerva.com/v2/search/matches")
.header("x-api-key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.gominerva.com/v2/search/matches")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"pagination": {
"page": 1,
"limit": 10,
"total_count": 1,
"total_pages": 1,
"has_next": false,
"has_prev": false
},
"matches": [
{
"id": "665f1c2b16f5adbb8e1d3f41",
"name": {
"value": "Natwest Logistics LLC"
},
"review_status": "suppressed",
"suppression_reason": "allowlist",
"allowlist": {
"status": "suppressed",
"mode": "suppress",
"list": {
"id": "cl_7f3a",
"name": "Payee allowlist",
"version_id": "clv_19e2",
"version_sequence": 5
},
"decided_by": "stage",
"evaluated_at": "2026-11-14T11:30:12Z"
}
}
]
}{
"message": "Missing required x-bulk-action-tenant-id header."
}{
"message": "Missing required x-bulk-action-tenant-id header."
}List stored potential matches
Returns the potential matches Minerva has stored for your searches. Every search stores its potential matches, including each monitoring rescreen, and this endpoint reads them back by search request, profile, review status, suppression reason, allowlist status, or time window. Results are newest first by default.
A filter with several values returns matches that have any of them. When you use more than one filter, a match must meet all of them.
When the request is scoped to a workspace, for example with the x-workspace-id header, only that workspace’s matches are returned.
Match IDs. Each item’s id identifies one stored potential match. It is the same value that PATCH /v2/search/matches/{match_id} accepts, so you can store it and use it later to record a review decision.
A synchronous POST /v2/search also returns this ID on each match as screening_match_id, when it is available. A match can also carry record_id, the data source’s own identifier for the matched record. record_id isn’t a match ID.
- The
iddoes not change for as long as the match exists. Updating a match’s review status keeps the sameid. - A new screening of the same subject, such as a monitoring rescreen, stores its matches with new IDs. Minerva never reuses the ID of an earlier match, so if a rescreen finds the same person or entity again, that potential match has a new
idand the new screening’srequest_id. - Minerva doesn’t expire stored matches automatically, and archiving a profile doesn’t remove its matches.
Pagination. Use page and limit, and read the pagination object in the response. has_next tells you whether another page exists. See Search History for monitoring and audit examples.
To audit allowlisting, filter by suppression_reason=allowlist (matches whose current suppression reason is Allowlisted) or by allowlist_status (how the allowlist screened the match, which stays on the match after a later review). For example, allowlist_status=record_changed,record_not_covered lists matches an entry no longer covers.
curl --request GET \
--url https://api.gominerva.com/v2/search/matches \
--header 'x-api-key: <api-key>'import requests
url = "https://api.gominerva.com/v2/search/matches"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};
fetch('https://api.gominerva.com/v2/search/matches', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.gominerva.com/v2/search/matches",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.gominerva.com/v2/search/matches"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("x-api-key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.gominerva.com/v2/search/matches")
.header("x-api-key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.gominerva.com/v2/search/matches")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"pagination": {
"page": 1,
"limit": 10,
"total_count": 1,
"total_pages": 1,
"has_next": false,
"has_prev": false
},
"matches": [
{
"id": "665f1c2b16f5adbb8e1d3f41",
"name": {
"value": "Natwest Logistics LLC"
},
"review_status": "suppressed",
"suppression_reason": "allowlist",
"allowlist": {
"status": "suppressed",
"mode": "suppress",
"list": {
"id": "cl_7f3a",
"name": "Payee allowlist",
"version_id": "clv_19e2",
"version_sequence": 5
},
"decided_by": "stage",
"evaluated_at": "2026-11-14T11:30:12Z"
}
}
]
}{
"message": "Missing required x-bulk-action-tenant-id header."
}{
"message": "Missing required x-bulk-action-tenant-id header."
}Authorizations
Headers
Query Parameters
Return matches with one of these review statuses, for example unresolved. Pass a comma-separated list or repeat the parameter. Values are compared exactly, so use the lowercase values the API returns.
unresolved, reopened, true_positive, false_positive, suppressed, closed, not_found Filter by allowlist.status, how the allowlist screened the match. Unknown values return 400.
suppressed, would_suppress, partially_covered, subject_not_matched, details_not_matched, record_not_covered, record_changed, entry_expired, entry_lifetime_exceeded Return matches that carry a hit on at least one of these feeds. Use the feed names that appear as keys of a match's hits, for example Sanctions, PEP, Criminal, Legal, News, Open Source, Social Media, Registries, Ownership, Offshore or Internal. Pass a comma-separated list or repeat the parameter. Feed names are case-sensitive.