Batch Search Results API

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

import requests

url = "https://api.gominerva.com/v1/search/{jobid}"

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/v1/search/{jobid}', 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/{jobid}",
  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/{jobid}"

	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/v1/search/{jobid}")
  .header("x-api-key", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.gominerva.com/v1/search/{jobid}")

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,
  "response": "complete",
  "submitted": 2,
  "completed": 2,
  "results": [
    {
      "id": "1624676726659826",
      "jobid": "25e15c07-1322-4364-a26e-2a6ef25c81d4",
      "status": "complete",
      "searchId": "<requestId>_0",
      "request": {
        "name": "John Example",
        "type": "individual",
        "feeds": [
          "Sanctions",
          "PEP",
          "News"
        ]
      },
      "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"
          ]
        }
      ]
    }
  ]
}

Batch Search Results API

I submitted an asynchronous search request and got a job ID. Now I want to check the job status and get the results of the batch if the screening is done. On successful submission of a response to the search endpoint, a job id will be returned. Use this job id to query the status of your search. If the search is in progress, it will return progress data indicating how far along the job is to completion. If the search is complete, then the full response object will be returned with the call. For every object in the requests object of the body that was submitted to /search, there will be a response profile object returned by this endpoint. Check out the Profile Data Schema for a detailed view of the profile object.

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

GET

{jobid}

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

import requests

url = "https://api.gominerva.com/v1/search/{jobid}"

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/v1/search/{jobid}', 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/{jobid}",
  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/{jobid}"

	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/v1/search/{jobid}")
  .header("x-api-key", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.gominerva.com/v1/search/{jobid}")

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,
  "response": "complete",
  "submitted": 2,
  "completed": 2,
  "results": [
    {
      "id": "1624676726659826",
      "jobid": "25e15c07-1322-4364-a26e-2a6ef25c81d4",
      "status": "complete",
      "searchId": "<requestId>_0",
      "request": {
        "name": "John Example",
        "type": "individual",
        "feeds": [
          "Sanctions",
          "PEP",
          "News"
        ]
      },
      "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.

Path Parameters

jobid

string<uuid>

required

The job ID of a former search submission to the search POST endpoint.

Response

The job id was valid, and either the status or the full search results are returned.

Automatic Disposition (New): when the workspace that submitted the batch has Automatic Disposition enabled with the Direct API channel turned on, Minerva analyzes every screened potential match in a row's results[] - one carrying at least one risk flag (Sanctions, PEP, News, Criminal, Legal, and so on) in checklist.screen - before that row completes, which can add a few seconds per screened entity to row completion. The same rows are returned by POST /v1/searchStatus.

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 the whole job out at submission by sending the X-Minerva-Automatic-Disposition: skip header on POST /v1/search (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

response

enum<string>

The current status of the batch search job

Available options:

complete,

pending,

error

Example:

"complete"

submitted

integer

Total number of search requests submitted in the batch

Example:

42

completed

integer

Number of search requests completed so far

Example:

42

results

object[]

Array of search results (only present when response is "complete")

Show child attributes

Batch Asynchronous Search API Single Search Synchronous API

⌘I

API Documentation

Screening - Endpoints

Admin Actions - Endpoints

Profiles - Endpoints

Agent Risk Assessments - Endpoints

Batch Search Results API

Authorizations

Path Parameters

Response