> ## 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. # 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](/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 Minerva core monolith, which provides search, consensus, pruning, and report generation. servers: - url: https://api.gominerva.com description: The production API server for Minerva. 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: Submit a batch search description: > 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](/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 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](/automatic-disposition-guide) 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). 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: the request format does not match the required schema. Check your JSON body formatting 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 judged the request data unsafe, usually because it contained script/code tags or injection motifs - Your account would 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: something went wrong on the Minerva server while completing this task, so it did not complete. Contact support@gominerva.com with reproduction notes so we can resolve it. 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 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. schema: type: string enum: - skip example: skip schemas: SearchRequest: type: object properties: type: enum: - Individual - Organization type: string description: >- The type of search to run. Individual searches and organization searches consider different type-specific fields, and different data sources. 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 of residence or operation for the individual or organization. Results from nearby cities may be returned when other criteria match strongly. state: type: string example: Ontario description: >- The last known state or province of residence or operation for the individual or organization. Supply the full state name, such as "New York". country: type: string example: Canada description: >- The known nationality, or the last known country of residence or operation, for the individual or organization. Supply a canonical full country name, such as "United States" or "United Kingdom". Values are normalized, so "United States" also matches "US" and "United States of America". occupation: type: string example: Software Developer description: >- The last known job title or occupation. This parameter is considered only for individual searches. organization: type: string example: MinervaAI description: >- The last known employer, or the organization the individual is a member of. This parameter is considered only for individual 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. A custom tag you can assign to the screen; Minerva stores it with the job request data and returns it when you query the job later. 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 you can assign to the screen; Minerva stores it with the job request data and returns it when you query the job later. required: - type - name SearchFeeds: type: array description: >- The allowed Minerva search feeds for the request. Provide one feed name, a combination of feed names, or "all" to select every available feed. 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 the request, ignoring the workspace Direct API Calls configuration. The set can 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 applies. If no workspace configuration exists, the standard 29-category default 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 threshold on the profile match score. Results below it are not returned. Default is 0.7 (70% match). example: 0.8 soft_match: type: boolean description: >- Whether to match softly. All parameters are matched softly using the Minerva scoring algorithm, so a search for gender "Male" may still return "Female" results when 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. ````