Single Search Synchronous API (GET)

curl --request GET \
  --url https://api.gominerva.com/v1/search-sync \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.gominerva.com/v1/search-sync', 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-sync",
  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/v1/search-sync"

	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))

}

require 'uri'
require 'net/http'

url = URI("https://api.gominerva.com/v1/search-sync")

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

{
  "status": 200,
  "message": "Search successfully completed.",
  "jobid": "adf48860-6a96-43a4-b008-37eccd139e3a",
  "duration": 4.56,
  "searchId": "69ba0b732908cb3209647d36",
  "pending": false,
  "dashboardViewLink": "https://app.gominerva.com/dashboard?requestId=REQUEST_ID&jobId=JOB_ID#results",
  "results": [
    {
      "type": 0,
      "name": {
        "value": "John Example",
        "match_score": 0.97,
        "criteria_match_level": "close"
      },
      "score": 0.97,
      "checklist": {
        "screen": {
          "Sanctions": true,
          "PEP": false,
          "News": false
        }
      },
      "review_status": "unresolved",
      "disposition_hint": {
        "prediction": "true_positive",
        "confidence": 0.99,
        "analysis_status": "completed",
        "source": "direct_api",
        "rationale": "The searched subject matches the potential match on name and country context, and no discovered identity attribute contradicts the match."
      },
      "sources": [
        "Example Sanctions List"
      ]
    },
    {
      "type": 0,
      "name": {
        "value": "John Example",
        "match_score": 0.92,
        "criteria_match_level": "close"
      },
      "score": 0.88,
      "checklist": {
        "screen": {
          "Sanctions": false,
          "PEP": true,
          "News": false
        }
      },
      "review_status": "false_positive",
      "automatic_disposition": {
        "prediction": "false_positive",
        "confidence": 0.95,
        "analysis_status": "completed",
        "source": "direct_api",
        "rationale": "The searched subject's occupation and country conflict with the listed person, and the date of birth reported by the triggering source does not align with the submitted subject."
      },
      "sources": [
        "Example Government Biography"
      ]
    },
    {
      "type": 0,
      "name": {
        "value": "John Example",
        "match_score": 0.9,
        "criteria_match_level": "close"
      },
      "score": 0.82,
      "checklist": {
        "screen": {
          "Sanctions": false,
          "PEP": false,
          "News": false
        }
      },
      "review_status": "unresolved",
      "sources": [
        "Example Corporate Registry"
      ]
    }
  ]
}

Legacy

Single Search Synchronous API (GET)

deprecated

Legacy synchronous single search via query parameters. This GET method is retained for backwards compatibility and simple name-only requests. For new integrations, use the canonical POST /v1/search-sync method, especially when supplying address, date of birth, or personal ID fields. Average completion time varies - full EDD search completes within 45 seconds, Sanctions and PEP searches typically complete in 300ms-3 seconds. All parameters are matched softly using the Minerva scoring algorithm.

New: matches in this response can include Automatic Disposition annotations - see the review_status, automatic_disposition, and disposition_hint response fields below and the Automatic Disposition Guide.

GET

search-sync

Single Search Synchronous API (GET)

curl --request GET \
  --url https://api.gominerva.com/v1/search-sync \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.gominerva.com/v1/search-sync', 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-sync",
  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/v1/search-sync"

	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))

}

require 'uri'
require 'net/http'

url = URI("https://api.gominerva.com/v1/search-sync")

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

{
  "status": 200,
  "message": "Search successfully completed.",
  "jobid": "adf48860-6a96-43a4-b008-37eccd139e3a",
  "duration": 4.56,
  "searchId": "69ba0b732908cb3209647d36",
  "pending": false,
  "dashboardViewLink": "https://app.gominerva.com/dashboard?requestId=REQUEST_ID&jobId=JOB_ID#results",
  "results": [
    {
      "type": 0,
      "name": {
        "value": "John Example",
        "match_score": 0.97,
        "criteria_match_level": "close"
      },
      "score": 0.97,
      "checklist": {
        "screen": {
          "Sanctions": true,
          "PEP": false,
          "News": false
        }
      },
      "review_status": "unresolved",
      "disposition_hint": {
        "prediction": "true_positive",
        "confidence": 0.99,
        "analysis_status": "completed",
        "source": "direct_api",
        "rationale": "The searched subject matches the potential match on name and country context, and no discovered identity attribute contradicts the match."
      },
      "sources": [
        "Example Sanctions List"
      ]
    },
    {
      "type": 0,
      "name": {
        "value": "John Example",
        "match_score": 0.92,
        "criteria_match_level": "close"
      },
      "score": 0.88,
      "checklist": {
        "screen": {
          "Sanctions": false,
          "PEP": true,
          "News": false
        }
      },
      "review_status": "false_positive",
      "automatic_disposition": {
        "prediction": "false_positive",
        "confidence": 0.95,
        "analysis_status": "completed",
        "source": "direct_api",
        "rationale": "The searched subject's occupation and country conflict with the listed person, and the date of birth reported by the triggering source does not align with the submitted subject."
      },
      "sources": [
        "Example Government Biography"
      ]
    },
    {
      "type": 0,
      "name": {
        "value": "John Example",
        "match_score": 0.9,
        "criteria_match_level": "close"
      },
      "score": 0.82,
      "checklist": {
        "screen": {
          "Sanctions": false,
          "PEP": false,
          "News": false
        }
      },
      "review_status": "unresolved",
      "sources": [
        "Example Corporate Registry"
      ]
    }
  ]
}

Authorizations

x-api-key

string

header

required

The Minerva API key used for this integration. Manage API keys in the Minerva dashboard under Administration > Developers.

Headers

X-Minerva-Automatic-Disposition

enum<string>

Opts this search request out of Automatic Disposition. The header only has an effect when your organization has been 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 it 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"

Query Parameters

type

enum<string>

required

The type of profile to search for. Should be "individual" or "organization".

Available options:

individual,

organization

name

string

required

The full legal name of the search subject.

feeds

string

required

A comma-separated array of feeds to include in the scope of the search. Must be selected from "Sanctions", "PEP", "Criminal", "Legal", "Offshore", "Open Source", "Ownership", "News", "Registries", "Social Media", or "all". Use "all" to select all available feeds.

gender

string

The gender of the individual. Only applicable for individual type searches. Matched softly.

year

integer

The full year integer describing when the individual was born, or that the organization was founded.

month

integer

The month integer describing when the individual was born, or that the organization was founded. Corresponds to calendar month integers (1 = January).

Required range: 1 <= x <= 12

day

integer

The calendar day integer describing when the individual was born, or that the organization was founded.

Required range: 1 <= x <= 31

city

string

The currently known town, city, or municipality of the profile.

state

string

The currently known state or province of the profile.

country

string

The currently known country or nationality of the profile.

occupation

string

The current job title or role of the individual. Only applicable for individual type searches.

organization

string

The current organization that the individual is associated with. Only applicable for individual type searches.

notes

string

Additional notes or information to narrow the results.

externalId

string

External identifier for tracking purposes.

address

string

The currently known address of the profile. Can include lines 1 and 2 in a single line.

phone

string

A E.164 compliant international phone number string associated with the profile.

string

A known email address associated with the profile.

regID

string

The registration ID of the organization. Only applicable for organization type searches.

match_threshold

number

Custom match threshold on the profile match score, below which results will not be returned.

max_lookback_days

number

Applies a max window on time in days for supported feeds. Currently only supported on the "News" feed for adverse media.

soft_match

boolean

Determines whether or not to use soft match. All parameters are matched softly using the Minerva scoring algorithm.

location_match_strictness

enum<string>

Applies a hard exclusion for any data points that do not match the geography at the specified resolution. Allowed values are "city", "state", and "country".

Available options:

city,

state,

country

omit_open_source

boolean

Determines whether or not to omit the open source feed for certain feeds that automatically include open source (e.g., PEP).

Response

Search successfully completed. Returns the search results synchronously.

Automatic Disposition (New): when the workspace that owns your API application has Automatic Disposition enabled with the Direct API channel turned on, Minerva analyzes every screened potential match in results[] - one carrying at least one risk flag (Sanctions, PEP, News, Criminal, Legal, and so on) in checklist.screen - before this response returns, which adds a few seconds per screened entity.

review_status changes only in Full Auto Mode: a prediction that meets the configured confidence threshold sets true_positive or false_positive, and the applied prediction is returned in automatic_disposition.
In Hint Mode the prediction is returned in disposition_hint and review_status stays unresolved - the annotation is advisory, for your integration to interpret in real time.
An analysis that completes without meeting a threshold returns disposition_hint with prediction: "undetermined" and the match stays unresolved.

Clean matches and workspaces without the feature enabled never carry these fields. The default response example shows annotated matches. Opt a single request out with the X-Minerva-Automatic-Disposition: skip header (inert unless the feature is enabled for the workspace), and see the Automatic Disposition Guide for consuming these fields in an integration.

status

integer

Example:

200

message

string

Example:

"Search successfully completed."

jobid

string

Example:

"adf48860-6a96-43a4-b008-37eccd139e3a"

duration

number

Elapsed execution time in seconds.

Example:

1.23

searchId

string

Search result identifier. Pass this value as searchResultId when generating a report with POST /v1/reports.

Example:

"69ba0b732908cb3209647d36"

pending

boolean

Whether the synchronous search still has pending work.

Example:

false

dashboardViewLink

string

Example:

"https://app.gominerva.com/dashboard?requestId=REQUEST_ID&jobId=JOB_ID#results"

request

object

Show child attributes

results

object[]

Up to 10 potential matches ranked by criteria match score. Each result is a Profile object containing rich profile information with source lineage.

Show child attributes

⌘I

API Documentation

Screening - Endpoints

Admin Actions - Endpoints

Profiles - Endpoints

Agent Risk Assessments - Endpoints

Single Search Synchronous API (GET)

Authorizations

Headers

Query Parameters

Response