> ## Documentation Index > Fetch the complete documentation index at: https://docs.gominerva.com/llms.txt > Use this file to discover all available pages before exploring further. # Batch Asynchronous Search API > **"I want to submit a batch of multiple searches at once to Minerva in an asynchronous way so that I can query the long running job later."** **"I want to submit large volumes of searches at once and query the results overnight to update my systems."** The search endpoint submits a search job and returns a job id which should be used to check on the status of the search. The search is performed in real-time and queries a combination of Minerva internal data as well as open web data. **Performance:** The average completion time of a Minerva search varies based on the feeds requested. A full EDD search, which includes all Minerva feeds, usually completes within 45 seconds. For Sanctions and PEP searches, the search time is often in the 300 millisecond to 3 second range. **Matching Algorithm:** All parameters are matched softly against the database, using the Minerva scoring algorithm. This means that searches for "Male" gender will not necessarily exclude "Female" results if other criteria match strongly enough to the requested parameters. The same is true for geography parameters, where results from nearby cities/states may be returned if enough other criteria match strongly. **Note:** This is the batch asynchronous search API endpoint, which is best used for longer running jobs that include lists of multiple searches at once. Obtaining the search results from this endpoint requires storing the job id to query later, or to poll until completion. If your intent is to submit a search for a single profile at a time and obtain the results for those searches immediately, then it would be better to apply 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](/api-reference/automatic-disposition-guide).

Adverse media risk categories configuration

When `News` 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](/adverse-media-categories) for category definitions, defaults, and precedence. ## OpenAPI ````yaml /api-reference/core.json post /v1/search openapi: 3.0.0 info: version: 1.6.2 title: MinervaAI Core API description: >- The MinervaAI core monolith that serves the search, consensus, pruning, and report generation capabilities. servers: - url: https://api.gominerva.com description: The production API server for Minerva AI security: - ApiKeyAuth: [] tags: - name: Search description: >- Current screening, search, and reporting endpoints for active integrations. - name: Legacy description: >- Legacy endpoints retained for backwards compatibility. Prefer the canonical POST-based search flows for new integrations. - name: API to UI Integration description: Endpoints used to bridge API integrations with Minerva UI workflows. - name: Potential Matches description: Update review workflow state for potential matches returned by searches. paths: /v1/search: post: tags: - Search summary: Batch Asynchronous Search API description: > **"I want to submit a batch of multiple searches at once to Minerva in an asynchronous way so that I can query the long running job later."** **"I want to submit large volumes of searches at once and query the results overnight to update my systems."** The search endpoint submits a search job and returns a job id which should be used to check on the status of the search. The search is performed in real-time and queries a combination of Minerva internal data as well as open web data. **Performance:** The average completion time of a Minerva search varies based on the feeds requested. A full EDD search, which includes all Minerva feeds, usually completes within 45 seconds. For Sanctions and PEP searches, the search time is often in the 300 millisecond to 3 second range. **Matching Algorithm:** All parameters are matched softly against the database, using the Minerva scoring algorithm. This means that searches for "Male" gender will not necessarily exclude "Female" results if other criteria match strongly enough to the requested parameters. The same is true for geography parameters, where results from nearby cities/states may be returned if enough other criteria match strongly. **Note:** This is the batch asynchronous search API endpoint, which is best used for longer running jobs that include lists of multiple searches at once. Obtaining the search results from this endpoint requires storing the job id to query later, or to poll until completion. If your intent is to submit a search for a single profile at a time and obtain the results for those searches immediately, then it would be better to apply 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](/api-reference/automatic-disposition-guide). parameters: - $ref: '#/components/parameters/AutomaticDispositionHeader' requestBody: required: true content: application/json: schema: type: object required: - requests - feeds properties: requests: type: array description: >- A list of JSON objects, each object corresponding to a single individual or entity in the batch. items: $ref: '#/components/schemas/SearchRequest' feeds: $ref: '#/components/schemas/SearchFeeds' example: 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 responses: '200': description: >- Requests successfully submitted. Returns a job ID that should be used with the /searchStatus endpoint to check on the status of the search and retrieve results when complete. **Automatic Disposition (New):** when the workspace that owns your API application has [Automatic Disposition](/automatic-disposition-guide) enabled with the **Direct API** channel turned on, screened potential matches are analyzed before each row completes (a few seconds per screened entity) and 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). content: application/json: schema: type: object properties: status: type: integer example: 200 message: type: string example: Requests successfully submitted id: type: string format: uuid description: >- Use this ID in the /searchStatus endpoint to get the status of the job and the search results. example: 25e15c07-1322-4364-a26e-2a6ef25c81d4 '400': description: > Bad Request - You made a request with a format that does not match the required schema. Please check your JSON body formatting for any issues, and refer to the schema above for allowed fields. content: application/json: schema: type: object properties: status: type: integer example: 400 message: type: string example: Empty or invalid body '403': description: > Forbidden - Authentication failed because: - The API key was invalid - A server-side safety check deemed the request data to be unsafe, usually because of the inclusion of script/code tags or injection motifs - Your account will overrun a hard quota if this call is made content: application/json: schema: type: object properties: status: type: integer example: 403 message: type: string example: Missing x-api-key header. '500': description: > Internal Server Error - An issue was encountered on the Minerva server side while attempting to complete this task, and it did not complete correctly. Please contact us at support@gominerva.com with bug reproduction notes to have this issue resolved. content: application/json: schema: type: object properties: status: type: integer example: 500 message: type: string example: >- Internal server error occurred while processing the request security: - ApiKeyAuth: [] components: parameters: AutomaticDispositionHeader: name: X-Minerva-Automatic-Disposition in: header required: false description: >- 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. schema: type: string enum: - skip example: skip schemas: SearchRequest: type: object properties: type: enum: - Individual - Organization type: string description: >- The type of search that is being requested. When requesting for an individual search vs an organization search, there are some different fields that are specific to each type that will be considered. Different data sources will be considered as well for individuals vs organizations. example: Individual name: type: string example: John Smith description: >- The full legal name of the individual or organization, including any middle names. gender: type: string enum: - Male - Female - Other description: >- The gender of the individual. Only applicable for individual type searches. Matched softly against the database. example: Male year: type: number example: 1970 description: >- The year that the individual was born, or the organization was created. month: type: number minimum: 1 maximum: 12 example: 6 description: >- The month that the individual was born, or the organization was created. day: type: number minimum: 1 maximum: 31 example: 11 description: >- The day that the individual was born, or the organization was created. city: type: string example: Toronto description: >- The last known city that the individual or organization was known to operate in. Results from nearby cities may be returned if other criteria match strongly. state: type: string example: Ontario description: >- The last known state or province that the individual or organization was known to operate in. This should be the full state name, such as "New York". country: type: string example: Canada description: >- The known nationality or the last known country that the individual or organization was known to operate in. This should be a canonical full country name, such as "United States" or "United Kingdom". Values will be normalized such that "United States" will match "US" and "United States of America". occupation: type: string example: Software Developer description: >- The last known job title or occupation. This query parameter will only be considered for Individual type searches. organization: type: string example: MinervaAI description: >- The last known employer or the organization that the individual is a member of. This query parameter will only be considered for Individual type searches. email: type: string example: john.smith@gmail.com description: The known email address of the individual or organization. phone: type: string example: '+15555555555' description: The known phone number of the individual or organization. personalID: type: string example: A1234-BCDEF-GHIJK description: >- For individual searches, any personal ID numbers such as a driver's license, passport number, or national ID. regID: type: string example: '19288709' description: >- For entity searches, any entity ID numbers such as a registration number. notes: type: string example: 'Personal website: www.johnsmith.com' description: >- Additional unstructured notes that can be provided to potentially narrow the search further using semantic cues and soft matching. externalId: type: string example: '12345678' description: >- External identifier for tracking purposes. A custom tag that can be assigned to the screen, which will be stored with the job request data when queried in the future. global_filters: $ref: '#/components/schemas/GlobalFilters' description: >- Global filtering options that apply to all feeds in the search request. feed_filters: $ref: '#/components/schemas/FeedFilters' description: >- Feed-specific filtering options that override global filters for individual feeds. custom_id: type: string example: customer_01 description: >- A custom tag that can be assigned to the screen, which will be stored with the job request data when queried in the future. required: - type - name SearchFeeds: type: array description: >- The allowed values for MinervaAI search feeds in the request. Provide one or a combination of the feed names, or the "all" value, which will automatically engage all the available search feeds. items: type: string enum: - all - Sanctions - PEP - Criminal - Legal - Offshore - Ownership - Registries - Social Media - News - Open Source GlobalFilters: type: object description: Global filtering options that apply to all feeds in the search request. properties: adverse_media_risk_categories: type: array items: type: string enum: - moneylaundering - terror_funding - terrorism - narcotics - recreational_drugs - auctions - rare_gems_metals - fine_art - cryptocurrency - fraud_bribery_corruption - sex_industry - sanctions - smuggling - casinos - cybercrime - insider_trading - foreign_ownership - human_trafficking - non_profit - luxury_vehicles - loan_companies - organized_crime - real_estate - tax_evasion - third_party_transactions - international_services - used_merchandise - weapons - other - dui - property_damage - assault_battery description: >- Per-request override of the workspace Adverse Media Risk Classification configuration. When present, adverse media analysis emits exactly this set of risk categories for this request, ignoring the workspace's Direct API Calls configuration; the set may also enable categories the workspace leaves disabled. Values are the raw snake_case category keys listed in this schema. An empty array disables every risk category for the request. Unknown names are rejected with an HTTP 400 response that identifies the offending values. When absent, the workspace configuration—or the standard 29-category default when no workspace configuration exists—applies. example: - moneylaundering - fraud_bribery_corruption - sanctions location_match_strictness: type: string enum: - city - state - country description: >- Applies a hard exclusion for any data points that do not match the geography at the specified resolution. example: city match_threshold: type: number minimum: 0 maximum: 1 description: >- Custom match threshold on the profile match score, below which results will not be returned. Default is 0.7 (70% match). example: 0.8 soft_match: type: boolean description: >- Determines whether to use soft matching. All parameters are matched softly using the Minerva scoring algorithm, meaning searches for "Male" gender may not exclude "Female" results if other criteria match strongly enough. example: true FeedFilters: type: object description: >- Feed-specific filtering options that override global filters for individual feeds. additionalProperties: type: object properties: location_match_strictness: type: string enum: - city - state - country description: Feed-specific location match strictness override. example: state soft_match: type: boolean description: Feed-specific soft match override. example: true match_threshold: type: number minimum: 0 maximum: 1 description: Feed-specific match threshold override. example: 0.8 example: Sanctions: location_match_strictness: country soft_match: true match_threshold: 0.9 securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- The Minerva API key used for this integration. Manage API keys in the Minerva dashboard under Administration > Developers. ````