Single Search Synchronous API
Canonical synchronous single search via request body for single individual or entity screening. Use this POST method for new integrations and whenever supplying combinations of PII such as name, address, date of birth, or personal ID fields for security reasons. 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.
Adverse media risk categories configuration
WhenNews is included in feeds, use global_filters.adverse_media_risk_categories to replace the workspace’s Direct API category set for this search. Send raw category keys from the request schema. The override may narrow or widen the workspace set, and an empty array disables every category for this call. 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 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.
skip "skip"
Body
The type of profile to search for.
individual, organization "individual"
The full legal name of the search subject.
"John Smith"
Array of feeds to include in the search scope.
The gender of the individual (individual searches only).
"Male"
Birth year for individuals or founding year for organizations.
1970
Birth/founding month (1 = January).
1 <= x <= 126
Birth/founding day.
1 <= x <= 3111
City, town, or municipality.
"Toronto"
State or province.
"Ontario"
Country or nationality.
"Canada"
Job title or role (individual searches only).
"Software Developer"
Associated organization (individual searches only).
"Minerva"
Full address including lines 1 and 2.
E.164 compliant international phone number.
Email address associated with the profile.
Personal ID such as passport or driver's license (individual searches only).
Social Security Number (individual searches only). Encrypted on server side.
Registration ID (organization searches only).
Additional notes or information.
"Personal website: www.johnsmith.com"
External identifier for tracking purposes.
"12345678"
Custom match threshold below which results will not be returned.
Max window in days for supported feeds (currently News feed only).
Global filtering options that apply to all feeds in the search request.
Whether to use soft matching (default behavior).
Geographic exclusion resolution level.
city, state, country Whether to omit open source feed for feeds that include it automatically.
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_statuschanges only in Full Auto Mode: a prediction that meets the configured confidence threshold setstrue_positiveorfalse_positive, and the applied prediction is returned inautomatic_disposition.- In Hint Mode the prediction is returned in
disposition_hintandreview_statusstaysunresolved- the annotation is advisory, for your integration to interpret in real time. - An analysis that completes without meeting a threshold returns
disposition_hintwithprediction: "undetermined"and the match staysunresolved.
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.
200
"Search successfully completed."
"adf48860-6a96-43a4-b008-37eccd139e3a"
Elapsed execution time in seconds.
1.23
Search result identifier. Pass this value as searchResultId when generating a report with POST /v1/reports.
"69ba0b732908cb3209647d36"
Whether the synchronous search still has pending work.
false
"https://app.gominerva.com/dashboard?requestId=REQUEST_ID&jobId=JOB_ID#results"
Up to 10 potential matches ranked by criteria match score, resolved using entity resolution technology. Each result is a Profile object containing rich profile information with source lineage.