Submit a batch search
curl --request POST \
--url https://api.gominerva.com/v1/search \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"requests": [
{
"type": "Individual",
"name": "John Smith",
"gender": "Male",
"year": 1970,
"month": 6,
"day": 11,
"city": "Toronto",
"state": "Ontario",
"country": "Canada",
"occupation": "Software Developer",
"organization": "MinervaAI",
"notes": "Personal website: www.johnsmith.com",
"externalId": "12345678",
"global_filters": {
"location_match_strictness": "city",
"match_threshold": 0.8,
"soft_match": true,
"adverse_media_risk_categories": [
"moneylaundering",
"fraud_bribery_corruption",
"sanctions"
]
},
"feed_filters": {
"Sanctions": {
"location_match_strictness": "country",
"soft_match": true,
"match_threshold": 0.8
}
}
}
],
"feeds": [
"Sanctions",
"PEP",
"Criminal",
"Legal",
"Ownership",
"Open Source",
"Offshore",
"Registries",
"News",
"Social Media"
]
}
'import requests
url = "https://api.gominerva.com/v1/search"
payload = {
"requests": [
{
"type": "Individual",
"name": "John Smith",
"gender": "Male",
"year": 1970,
"month": 6,
"day": 11,
"city": "Toronto",
"state": "Ontario",
"country": "Canada",
"occupation": "Software Developer",
"organization": "MinervaAI",
"notes": "Personal website: www.johnsmith.com",
"externalId": "12345678",
"global_filters": {
"location_match_strictness": "city",
"match_threshold": 0.8,
"soft_match": True,
"adverse_media_risk_categories": ["moneylaundering", "fraud_bribery_corruption", "sanctions"]
},
"feed_filters": { "Sanctions": {
"location_match_strictness": "country",
"soft_match": True,
"match_threshold": 0.8
} }
}
],
"feeds": ["Sanctions", "PEP", "Criminal", "Legal", "Ownership", "Open Source", "Offshore", "Registries", "News", "Social Media"]
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
requests: [
{
type: 'Individual',
name: 'John Smith',
gender: 'Male',
year: 1970,
month: 6,
day: 11,
city: 'Toronto',
state: 'Ontario',
country: 'Canada',
occupation: 'Software Developer',
organization: 'MinervaAI',
notes: 'Personal website: www.johnsmith.com',
externalId: '12345678',
global_filters: {
location_match_strictness: 'city',
match_threshold: 0.8,
soft_match: true,
adverse_media_risk_categories: ['moneylaundering', 'fraud_bribery_corruption', 'sanctions']
},
feed_filters: {
Sanctions: {location_match_strictness: 'country', soft_match: true, match_threshold: 0.8}
}
}
],
feeds: [
'Sanctions',
'PEP',
'Criminal',
'Legal',
'Ownership',
'Open Source',
'Offshore',
'Registries',
'News',
'Social Media'
]
})
};
fetch('https://api.gominerva.com/v1/search', 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/v1/search",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'requests' => [
[
'type' => 'Individual',
'name' => 'John Smith',
'gender' => 'Male',
'year' => 1970,
'month' => 6,
'day' => 11,
'city' => 'Toronto',
'state' => 'Ontario',
'country' => 'Canada',
'occupation' => 'Software Developer',
'organization' => 'MinervaAI',
'notes' => 'Personal website: www.johnsmith.com',
'externalId' => '12345678',
'global_filters' => [
'location_match_strictness' => 'city',
'match_threshold' => 0.8,
'soft_match' => true,
'adverse_media_risk_categories' => [
'moneylaundering',
'fraud_bribery_corruption',
'sanctions'
]
],
'feed_filters' => [
'Sanctions' => [
'location_match_strictness' => 'country',
'soft_match' => true,
'match_threshold' => 0.8
]
]
]
],
'feeds' => [
'Sanctions',
'PEP',
'Criminal',
'Legal',
'Ownership',
'Open Source',
'Offshore',
'Registries',
'News',
'Social Media'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"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"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.gominerva.com/v1/search"
payload := strings.NewReader("{\n \"requests\": [\n {\n \"type\": \"Individual\",\n \"name\": \"John Smith\",\n \"gender\": \"Male\",\n \"year\": 1970,\n \"month\": 6,\n \"day\": 11,\n \"city\": \"Toronto\",\n \"state\": \"Ontario\",\n \"country\": \"Canada\",\n \"occupation\": \"Software Developer\",\n \"organization\": \"MinervaAI\",\n \"notes\": \"Personal website: www.johnsmith.com\",\n \"externalId\": \"12345678\",\n \"global_filters\": {\n \"location_match_strictness\": \"city\",\n \"match_threshold\": 0.8,\n \"soft_match\": true,\n \"adverse_media_risk_categories\": [\n \"moneylaundering\",\n \"fraud_bribery_corruption\",\n \"sanctions\"\n ]\n },\n \"feed_filters\": {\n \"Sanctions\": {\n \"location_match_strictness\": \"country\",\n \"soft_match\": true,\n \"match_threshold\": 0.8\n }\n }\n }\n ],\n \"feeds\": [\n \"Sanctions\",\n \"PEP\",\n \"Criminal\",\n \"Legal\",\n \"Ownership\",\n \"Open Source\",\n \"Offshore\",\n \"Registries\",\n \"News\",\n \"Social Media\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.gominerva.com/v1/search")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"requests\": [\n {\n \"type\": \"Individual\",\n \"name\": \"John Smith\",\n \"gender\": \"Male\",\n \"year\": 1970,\n \"month\": 6,\n \"day\": 11,\n \"city\": \"Toronto\",\n \"state\": \"Ontario\",\n \"country\": \"Canada\",\n \"occupation\": \"Software Developer\",\n \"organization\": \"MinervaAI\",\n \"notes\": \"Personal website: www.johnsmith.com\",\n \"externalId\": \"12345678\",\n \"global_filters\": {\n \"location_match_strictness\": \"city\",\n \"match_threshold\": 0.8,\n \"soft_match\": true,\n \"adverse_media_risk_categories\": [\n \"moneylaundering\",\n \"fraud_bribery_corruption\",\n \"sanctions\"\n ]\n },\n \"feed_filters\": {\n \"Sanctions\": {\n \"location_match_strictness\": \"country\",\n \"soft_match\": true,\n \"match_threshold\": 0.8\n }\n }\n }\n ],\n \"feeds\": [\n \"Sanctions\",\n \"PEP\",\n \"Criminal\",\n \"Legal\",\n \"Ownership\",\n \"Open Source\",\n \"Offshore\",\n \"Registries\",\n \"News\",\n \"Social Media\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.gominerva.com/v1/search")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"requests\": [\n {\n \"type\": \"Individual\",\n \"name\": \"John Smith\",\n \"gender\": \"Male\",\n \"year\": 1970,\n \"month\": 6,\n \"day\": 11,\n \"city\": \"Toronto\",\n \"state\": \"Ontario\",\n \"country\": \"Canada\",\n \"occupation\": \"Software Developer\",\n \"organization\": \"MinervaAI\",\n \"notes\": \"Personal website: www.johnsmith.com\",\n \"externalId\": \"12345678\",\n \"global_filters\": {\n \"location_match_strictness\": \"city\",\n \"match_threshold\": 0.8,\n \"soft_match\": true,\n \"adverse_media_risk_categories\": [\n \"moneylaundering\",\n \"fraud_bribery_corruption\",\n \"sanctions\"\n ]\n },\n \"feed_filters\": {\n \"Sanctions\": {\n \"location_match_strictness\": \"country\",\n \"soft_match\": true,\n \"match_threshold\": 0.8\n }\n }\n }\n ],\n \"feeds\": [\n \"Sanctions\",\n \"PEP\",\n \"Criminal\",\n \"Legal\",\n \"Ownership\",\n \"Open Source\",\n \"Offshore\",\n \"Registries\",\n \"News\",\n \"Social Media\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"status": 200,
"message": "Requests successfully submitted",
"id": "25e15c07-1322-4364-a26e-2a6ef25c81d4"
}{
"status": 400,
"message": "Empty or invalid body"
}{
"status": 403,
"message": "Missing x-api-key header."
}{
"status": 500,
"message": "Internal server error occurred while processing the request"
}Search
Submit a batch search
Submit a batch of searches as one asynchronous job, so you can query the long-running job later. This suits large volumes of searches whose results you collect later, for example overnight, to update your systems.
The search endpoint submits a search job and returns a job ID you use to check the status of the search. The search runs in real time and queries a combination of Minerva internal data and open web data.
Performance: average completion time depends on the feeds requested. A full EDD search, which includes all Minerva feeds, usually completes within 45 seconds. Sanctions and PEP searches usually complete in 300 milliseconds to 3 seconds.
Matching algorithm: all parameters are matched softly against the database using the Minerva scoring algorithm. A search for gender “Male” therefore does not necessarily exclude “Female” results when other criteria match strongly enough. The same applies to geography parameters: results from nearby cities or states may be returned when enough other criteria match strongly.
Note: this is the batch asynchronous search endpoint, best suited to longer-running jobs that contain lists of searches. Retrieving the results requires storing the job ID for a later query, or polling until the job completes. To search for a single profile and get its results immediately, use the synchronous search API.
New: potential matches in this job’s completed rows can include Automatic Disposition annotations. See the Batch Search Results response fields and the Automatic Disposition Guide.
POST
/
v1
/
search
Submit a batch search
curl --request POST \
--url https://api.gominerva.com/v1/search \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"requests": [
{
"type": "Individual",
"name": "John Smith",
"gender": "Male",
"year": 1970,
"month": 6,
"day": 11,
"city": "Toronto",
"state": "Ontario",
"country": "Canada",
"occupation": "Software Developer",
"organization": "MinervaAI",
"notes": "Personal website: www.johnsmith.com",
"externalId": "12345678",
"global_filters": {
"location_match_strictness": "city",
"match_threshold": 0.8,
"soft_match": true,
"adverse_media_risk_categories": [
"moneylaundering",
"fraud_bribery_corruption",
"sanctions"
]
},
"feed_filters": {
"Sanctions": {
"location_match_strictness": "country",
"soft_match": true,
"match_threshold": 0.8
}
}
}
],
"feeds": [
"Sanctions",
"PEP",
"Criminal",
"Legal",
"Ownership",
"Open Source",
"Offshore",
"Registries",
"News",
"Social Media"
]
}
'import requests
url = "https://api.gominerva.com/v1/search"
payload = {
"requests": [
{
"type": "Individual",
"name": "John Smith",
"gender": "Male",
"year": 1970,
"month": 6,
"day": 11,
"city": "Toronto",
"state": "Ontario",
"country": "Canada",
"occupation": "Software Developer",
"organization": "MinervaAI",
"notes": "Personal website: www.johnsmith.com",
"externalId": "12345678",
"global_filters": {
"location_match_strictness": "city",
"match_threshold": 0.8,
"soft_match": True,
"adverse_media_risk_categories": ["moneylaundering", "fraud_bribery_corruption", "sanctions"]
},
"feed_filters": { "Sanctions": {
"location_match_strictness": "country",
"soft_match": True,
"match_threshold": 0.8
} }
}
],
"feeds": ["Sanctions", "PEP", "Criminal", "Legal", "Ownership", "Open Source", "Offshore", "Registries", "News", "Social Media"]
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
requests: [
{
type: 'Individual',
name: 'John Smith',
gender: 'Male',
year: 1970,
month: 6,
day: 11,
city: 'Toronto',
state: 'Ontario',
country: 'Canada',
occupation: 'Software Developer',
organization: 'MinervaAI',
notes: 'Personal website: www.johnsmith.com',
externalId: '12345678',
global_filters: {
location_match_strictness: 'city',
match_threshold: 0.8,
soft_match: true,
adverse_media_risk_categories: ['moneylaundering', 'fraud_bribery_corruption', 'sanctions']
},
feed_filters: {
Sanctions: {location_match_strictness: 'country', soft_match: true, match_threshold: 0.8}
}
}
],
feeds: [
'Sanctions',
'PEP',
'Criminal',
'Legal',
'Ownership',
'Open Source',
'Offshore',
'Registries',
'News',
'Social Media'
]
})
};
fetch('https://api.gominerva.com/v1/search', 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/v1/search",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'requests' => [
[
'type' => 'Individual',
'name' => 'John Smith',
'gender' => 'Male',
'year' => 1970,
'month' => 6,
'day' => 11,
'city' => 'Toronto',
'state' => 'Ontario',
'country' => 'Canada',
'occupation' => 'Software Developer',
'organization' => 'MinervaAI',
'notes' => 'Personal website: www.johnsmith.com',
'externalId' => '12345678',
'global_filters' => [
'location_match_strictness' => 'city',
'match_threshold' => 0.8,
'soft_match' => true,
'adverse_media_risk_categories' => [
'moneylaundering',
'fraud_bribery_corruption',
'sanctions'
]
],
'feed_filters' => [
'Sanctions' => [
'location_match_strictness' => 'country',
'soft_match' => true,
'match_threshold' => 0.8
]
]
]
],
'feeds' => [
'Sanctions',
'PEP',
'Criminal',
'Legal',
'Ownership',
'Open Source',
'Offshore',
'Registries',
'News',
'Social Media'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"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"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.gominerva.com/v1/search"
payload := strings.NewReader("{\n \"requests\": [\n {\n \"type\": \"Individual\",\n \"name\": \"John Smith\",\n \"gender\": \"Male\",\n \"year\": 1970,\n \"month\": 6,\n \"day\": 11,\n \"city\": \"Toronto\",\n \"state\": \"Ontario\",\n \"country\": \"Canada\",\n \"occupation\": \"Software Developer\",\n \"organization\": \"MinervaAI\",\n \"notes\": \"Personal website: www.johnsmith.com\",\n \"externalId\": \"12345678\",\n \"global_filters\": {\n \"location_match_strictness\": \"city\",\n \"match_threshold\": 0.8,\n \"soft_match\": true,\n \"adverse_media_risk_categories\": [\n \"moneylaundering\",\n \"fraud_bribery_corruption\",\n \"sanctions\"\n ]\n },\n \"feed_filters\": {\n \"Sanctions\": {\n \"location_match_strictness\": \"country\",\n \"soft_match\": true,\n \"match_threshold\": 0.8\n }\n }\n }\n ],\n \"feeds\": [\n \"Sanctions\",\n \"PEP\",\n \"Criminal\",\n \"Legal\",\n \"Ownership\",\n \"Open Source\",\n \"Offshore\",\n \"Registries\",\n \"News\",\n \"Social Media\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.gominerva.com/v1/search")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"requests\": [\n {\n \"type\": \"Individual\",\n \"name\": \"John Smith\",\n \"gender\": \"Male\",\n \"year\": 1970,\n \"month\": 6,\n \"day\": 11,\n \"city\": \"Toronto\",\n \"state\": \"Ontario\",\n \"country\": \"Canada\",\n \"occupation\": \"Software Developer\",\n \"organization\": \"MinervaAI\",\n \"notes\": \"Personal website: www.johnsmith.com\",\n \"externalId\": \"12345678\",\n \"global_filters\": {\n \"location_match_strictness\": \"city\",\n \"match_threshold\": 0.8,\n \"soft_match\": true,\n \"adverse_media_risk_categories\": [\n \"moneylaundering\",\n \"fraud_bribery_corruption\",\n \"sanctions\"\n ]\n },\n \"feed_filters\": {\n \"Sanctions\": {\n \"location_match_strictness\": \"country\",\n \"soft_match\": true,\n \"match_threshold\": 0.8\n }\n }\n }\n ],\n \"feeds\": [\n \"Sanctions\",\n \"PEP\",\n \"Criminal\",\n \"Legal\",\n \"Ownership\",\n \"Open Source\",\n \"Offshore\",\n \"Registries\",\n \"News\",\n \"Social Media\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.gominerva.com/v1/search")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"requests\": [\n {\n \"type\": \"Individual\",\n \"name\": \"John Smith\",\n \"gender\": \"Male\",\n \"year\": 1970,\n \"month\": 6,\n \"day\": 11,\n \"city\": \"Toronto\",\n \"state\": \"Ontario\",\n \"country\": \"Canada\",\n \"occupation\": \"Software Developer\",\n \"organization\": \"MinervaAI\",\n \"notes\": \"Personal website: www.johnsmith.com\",\n \"externalId\": \"12345678\",\n \"global_filters\": {\n \"location_match_strictness\": \"city\",\n \"match_threshold\": 0.8,\n \"soft_match\": true,\n \"adverse_media_risk_categories\": [\n \"moneylaundering\",\n \"fraud_bribery_corruption\",\n \"sanctions\"\n ]\n },\n \"feed_filters\": {\n \"Sanctions\": {\n \"location_match_strictness\": \"country\",\n \"soft_match\": true,\n \"match_threshold\": 0.8\n }\n }\n }\n ],\n \"feeds\": [\n \"Sanctions\",\n \"PEP\",\n \"Criminal\",\n \"Legal\",\n \"Ownership\",\n \"Open Source\",\n \"Offshore\",\n \"Registries\",\n \"News\",\n \"Social Media\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"status": 200,
"message": "Requests successfully submitted",
"id": "25e15c07-1322-4364-a26e-2a6ef25c81d4"
}{
"status": 400,
"message": "Empty or invalid body"
}{
"status": 403,
"message": "Missing x-api-key header."
}{
"status": 500,
"message": "Internal server error occurred while processing the request"
}Adverse media risk categories configuration
WhenNews is included in feeds, use requests[].global_filters.adverse_media_risk_categories to replace the workspace’s Direct API category set for an individual entity in the batch. Each request object may use a different set. Send raw category keys from the request schema; an empty array disables every category for that entity. Omit the field to use workspace configuration. See Adverse Media Categories for category definitions, defaults, and precedence.Authorizations
The Minerva API key used for this integration. Manage API keys in the Minerva dashboard under Administration > Developers.
Headers
Opts this search request out of Automatic Disposition. The header has an effect only when your organization is opted into Automatic Disposition and an administrator has enabled it with the Direct API channel turned on in the workspace of the application whose API key you are using. Otherwise the header is inert and the search behaves as if the feature is off. Send the value skip (matched case-insensitively) to leave every returned match unresolved even when the feature is enabled for the workspace. Other values are ignored.
Available options:
skip Example:
"skip"
Body
application/json
A list of JSON objects, each object corresponding to a single individual or entity in the batch.
Show child attributes
Show child attributes
The allowed Minerva search feeds for the request. Provide one feed name, a combination of feed names, or "all" to select every available feed. "Internal" searches the custom lists active in the workspace and is included in "all" only when the workspace's allowedScreeningFeeds lists Internal explicitly and Minerva has not limited your account to feeds that leave out Internal; send ["all", "Internal"] to add it.
Available options:
all, Sanctions, PEP, Criminal, Legal, Offshore, Ownership, Registries, Social Media, News, Open Source, Internal Response
Requests successfully submitted. Returns a job ID to use with the /searchStatus endpoint to check the status of the search and retrieve results when complete.
Automatic Disposition (New): when the workspace that owns your API application has Automatic Disposition enabled with the Direct API channel turned on, Minerva analyzes screened potential matches before each row completes (a few seconds per screened entity), and the rows carry automatic_disposition or disposition_hint annotations when you retrieve the results with POST /v1/searchStatus or GET /v1/search/{jobid}. Send the X-Minerva-Automatic-Disposition: skip header with this submission to opt every row in the job out (inert unless the feature is enabled for the workspace).