> ## 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 v2 search > Submits one or more screening entities for synchronous or asynchronous execution. The optional config.submission_source value user_dashboard_risk_assessment is reserved for manual User Dashboard submissions authenticated with x-user-token; API-key and internal-key callers must omit it. ## OpenAPI ````yaml /api-reference/core.json post /v2/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: /v2/search: post: tags: - Search summary: Submit a v2 search description: >- Submits one or more screening entities for synchronous or asynchronous execution. The optional config.submission_source value user_dashboard_risk_assessment is reserved for manual User Dashboard submissions authenticated with x-user-token; API-key and internal-key callers must omit it. parameters: - $ref: '#/components/parameters/AutomaticDispositionHeader' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/V2SearchSubmissionRequest' example: config: execution_mode: async submission_source: user_dashboard_risk_assessment entities: - type: individual name: Alice Example feeds: - Sanctions - PEP global_filters: match_scoring_workflow: risk_assessment responses: '200': description: >- No entity was accepted; the response contains per-entity validation errors. content: application/json: schema: $ref: '#/components/schemas/V2SearchSubmissionResponse' '202': description: At least one entity was accepted and a search job was created. content: application/json: schema: $ref: '#/components/schemas/V2SearchSubmissionResponse' '400': description: >- Invalid request shape, unsupported execution mode or submission_source, or body-level `global_filters` / `feed_filters` (filters belong on each entity). content: application/json: schema: $ref: '#/components/schemas/MessageOnlyErrorBody' '403': description: >- Authentication or feed access failed, or a non-user-token caller attempted to set the reserved dashboard submission_source. content: application/json: schema: $ref: '#/components/schemas/MessageOnlyErrorBody' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/MessageOnlyErrorBody' security: - ApiKeyAuth: [] - UserTokenAuth: [] 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: V2SearchSubmissionRequest: type: object properties: config: $ref: '#/components/schemas/V2SearchSubmissionConfig' entities: type: array minItems: 1 maxItems: 100 items: $ref: '#/components/schemas/V2SearchSubmissionEntity' required: - config - entities V2SearchSubmissionResponse: type: object properties: job_id: type: string description: Search job identifier when at least one entity was accepted. request_id: type: string description: >- Persisted search-request identifier when at least one entity was accepted. dashboardViewLink: type: string format: uri errors: type: object additionalProperties: type: object properties: message: type: string required: - message entity_matches: type: object additionalProperties: $ref: '#/components/schemas/V2SearchSubmissionMatchesBody' description: >- Synchronous match results keyed by entity index when execution_mode is sync. MessageOnlyErrorBody: type: object properties: message: type: string example: Missing required x-bulk-action-tenant-id header. required: - message V2SearchSubmissionConfig: type: object description: Execution and request-provenance configuration for POST /v2/search. properties: execution_mode: type: string enum: - sync - async billable_tag: type: string description: >- Optional billing or workflow attribution tag. The value `onboarding` marks the submission as an Onboarding Screen: it resolves the onboarding submission origin and, for prepaid tenants, excludes the search from search-credit admission and the search delivery debit because an Onboarding Screen is billed once as its own debit kind at delivery of its results. submission_source: type: string enum: - user_dashboard_risk_assessment description: >- Optional trusted provenance for a manual User Dashboard risk-assessment submission. Only authenticated x-user-token sessions may set this value; API-key and internal-key callers must omit it. required: - execution_mode V2SearchSubmissionEntity: type: object description: >- One screening entity. Each entity carries its own `global_filters` and `feed_filters`; body-level filter objects are rejected by POST /v2/search. Accepts the same identifying fields as the v1 search request (gender, year, month, day, address, city, state, country, occupation, organization, email, phone, personalID, regID, notes, and their snake_case aliases) in addition to the properties listed here. properties: type: type: string description: >- Entity type. Accepts the same individual/organization values and legacy aliases as the v1 search request. example: individual name: type: string example: Alice Example feeds: $ref: '#/components/schemas/SearchFeeds' custom_id: type: string example: customer-case-42 external_id: type: string example: '12345678' global_filters: $ref: '#/components/schemas/GlobalFilters' description: >- Global filtering options applied to every feed in this entity's search. feed_filters: $ref: '#/components/schemas/FeedFilters' description: >- Feed-specific filtering options for this entity, overriding its global filters per feed. required: - type additionalProperties: true V2SearchSubmissionMatchesBody: type: object properties: metadata: $ref: '#/components/schemas/V2SearchSubmissionMatchMetadata' matches: type: array items: $ref: '#/components/schemas/Profile' required: - metadata - matches 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 pre_resolution_match_threshold: type: number description: >- Match threshold applied to all feeds during pre-resolution scoring. Values greater than 0 are clamped to a minimum of 0.6; a value of 0 or less is treated as unset. A feed-level "feed_filters..pre_resolution_match_threshold" overrides it for candidates with a checklist hit in that feed. Also accepted as "preResolutionMatchThreshold". example: 0.8 post_resolution_match_threshold: type: number description: >- Match threshold applied to all feeds during post-resolution scoring. Values greater than 0 are clamped to a minimum of 0.6; a value of 0 or less is treated as unset. A feed-level "feed_filters..post_resolution_match_threshold" overrides it. This stage threshold only decides which candidates survive that scoring stage: the final output cutoff reads the global output threshold, which is "match_threshold" when present and otherwise this value. Sanctions and PEP watchlist candidates are floored at "candidateScoring.gates.sanctionsPepThresholdOverride" (default 0.75) at this stage: a lower value does not loosen those candidates below the floor, while a higher value still tightens them. Also accepted as "postResolutionMatchThreshold". example: 0.75 max_requested_articles: type: integer description: >- Cap on the number of articles requested from each news provider that supports an article-count window. Values are clamped to the 100-750 range: anything below 100 behaves as 100 and anything above 750 as 750. When omitted, the engine's default (currently 300) applies. Feed-level "feed_filters..max_requested_articles" overrides it for that feed. example: 300 match_scoring_workflow: type: string description: >- Selects the workflow whose default thresholds apply to this search. Also accepted as "screening_origin" and "request_origin". Matching is case-insensitive. The engine's mapping resolves the default post-resolution output threshold as direct_api (also direct-api, api, or an absent value) -> 0.75, risk_assessment (also risk-assessment, risk_assessments, ui) -> 0.7, and onboarding/ongoing_monitoring (also monitoring, ongoing-monitoring) -> 0.85; any other value falls back to 0.75. The marker also selects the tenant's per-channel excluded sources. example: direct_api match_scoring_runtime_config: type: object description: >- Canonical nested object for per-request match-scoring overrides. It is also accepted as "matchScoringRuntimeConfig", "match_scoring_config", or "matchScoringConfig", and flat "match_scoring_*" aliases are normalized into the same shape; on a conflicting key the flat alias wins. Sections: "candidateScoring" (evidence weights for the pre- and post-resolution stages, plus stage thresholds and pre-score gates), "nameMatching" (person and organization name-similarity behaviour), "dobMatching" (date-of-birth, incorporation, and inferred-date behaviour), "locationMatching" (location strictness and nationality-as-country matching), "entityResolution" (merge thresholds and the strong-organization shortcut), and "openSource" (post-resolution web/SERP result quality). Unknown keys inside a section are ignored. properties: candidateScoring: type: object description: >- Evidence weights for each scoring stage and the stage thresholds and pre-score gates. "preResolutionWeights" and "postResolutionWeights" take the same weight key set as the tenant configuration; the location block splits into the four component keys described there. properties: preResolutionWeights: type: object description: >- Weights for the pre-resolution scoring stage. The location block has two mutually exclusive shapes, described on "locationAddress". properties: location: type: number description: >- Legacy total weight for the whole location block. The API accepts 0 to 10 and clamps to that range; the dashboard slider that normally sets this value constrains it to 0 to 1. It decides the block only when no location component is set below, in which case the block weighs this value and each component is a quarter of it. Setting any component makes this key irrelevant for that block. locationAddress: type: number description: >- Optional weight for the address-line component of the location block. The API accepts 0 to 10 and clamps to that range; the dashboard slider that normally sets these values constrains them to 0 to 1. The block has two mutually exclusive shapes. When none of locationAddress, locationCity, locationState, and locationCountry is set, the legacy shape applies: the block weighs "location" (or the stage default, 0.1 pre-resolution and 0.75 post-resolution) and each component is a quarter of it, so the post-resolution default is 0.1875 each, score-identical to the pre-split build. When at least one component is set, the component shape applies: unset components resolve to 0, the block weighs the sum of the components present, and "location" is not consulted. A component weight of 0 disables that component for scoring, for its strict-location gate, and for its missing-evidence charge; a component the candidate lacks stays excluded from the comparison instead of scoring 0. locationCity: type: number description: >- City component of the location block. Same contract as "locationAddress": optional, and setting any of the four components selects the component shape. locationState: type: number description: >- State or province component of the location block. Same contract as "locationAddress": optional, and setting any of the four components selects the component shape. locationCountry: type: number description: >- Country component of the location block. Same contract as "locationAddress": optional, and setting any of the four components selects the component shape; setting only this key makes the block weigh exactly this value. additionalProperties: true postResolutionWeights: type: object description: >- Weights for the post-resolution scoring stage. Same key set and the same two location shapes as "preResolutionWeights". properties: location: type: number description: >- Legacy total weight for the post-resolution location block. Same range (0 to 10 in the API, 0 to 1 in the dashboard) and same two-shape contract as the pre-resolution "location". locationAddress: type: number description: >- Address-line component of the post-resolution location block. Same contract as the pre-resolution "locationAddress"; with no component set the default split is 0.1875 per component for the 0.75 location weight. locationCity: type: number description: >- City component of the post-resolution location block. Same contract as the pre-resolution "locationAddress". locationState: type: number description: >- State or province component of the post-resolution location block. Same contract as the pre-resolution "locationAddress". locationCountry: type: number description: >- Country component of the post-resolution location block. Same contract as the pre-resolution "locationAddress". additionalProperties: true additionalProperties: true additionalProperties: true example: candidateScoring: postResolutionWeights: locationAddress: 0.6 locationCity: 0.1 locationState: 0 locationCountry: 0.05 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 V2SearchSubmissionMatchMetadata: type: object properties: request_id: type: string index_in_request: type: string external_id: type: string custom_id: type: string profile_id: type: string potential_match_hashes: type: object additionalProperties: type: string custom_list_feed_statuses: $ref: '#/components/schemas/CustomListFeedStatuses' feed_statuses: type: object description: >- ENG-3707: per-feed acquisition health for this entity, keyed by public feed name. Omitted when every feed answered cleanly. additionalProperties: $ref: '#/components/schemas/FeedStatus' partial: type: boolean description: >- ENG-3707: true iff any feed in feed_statuses is not available, i.e. a zero-result execution for this entity is not evidence of absence. required: - request_id - index_in_request Profile: type: object description: >- Schema for the screening results of a single profile. Includes source lineage for entity resolution and compliance screening. properties: type: type: integer enum: - 0 - 1 description: The type of profile. 0 for individual, 1 for organization. example: 0 name: $ref: '#/components/schemas/SourcedName' description: The primary name of the profile with source lineage. last_updated: type: string description: String timestamp of when the profile was last updated. example: Saturday, Jun 26 2021 - 03:05:55 GMT00:00 merge_id: type: string description: The unique ID of this profile in the knowledge graph. example: merge_abc123 pep_level: type: integer minimum: 1 maximum: 4 description: PEP inference tier from 1-4, where 1 is highest risk. example: 2 aliases: type: array description: >- Other known names for the profile, including names in non-Latin character sets. items: $ref: '#/components/schemas/SourcedName' gender: $ref: '#/components/schemas/SourcedGender' description: >- The gender of the profile. Only present for individual type profiles. company_type: $ref: '#/components/schemas/SourcedString' description: The type of company. Only present for organization type profiles. industry: $ref: '#/components/schemas/SourcedString' description: The industry of the profile. company_size: $ref: '#/components/schemas/SourcedString' description: >- The size of the company. Only present for organization type profiles. status: $ref: '#/components/schemas/SourcedString' description: >- The current status of the profile. For corporations, indicates company status such as "active" or "dissolved". occupation: $ref: '#/components/schemas/SourcedString' description: >- The job title or position of the individual. Only present for individual type profiles. organization: $ref: '#/components/schemas/SourcedString' description: >- The employer, affiliated entity, political party, or other organization associated with the individual. Only present for individual type profiles. nationality: $ref: '#/components/schemas/SourcedString' description: >- The known nationality or affiliated country of the profile. Contains the full country name. time_begin: $ref: '#/components/schemas/SourcedDate' description: >- The date of birth of the individual, or the date of incorporation/date active of the organization. time_end: $ref: '#/components/schemas/SourcedDate' description: >- If known/applicable, the date deceased of the individual or date of closure of the organization. alt_times: type: array description: Other known dates of birth or incorporation for the profile. items: $ref: '#/components/schemas/SourcedDate' place_of_birth: $ref: '#/components/schemas/SourcedString' description: >- The place of birth of the individual. May contain city, state, and/or country. contact: $ref: '#/components/schemas/ProfileContact' description: Contact information including email and phone. media: $ref: '#/components/schemas/ProfileMedia' description: >- Media for the profile, including adverse and neutral media URLs and social media usernames. Present when the News, Open Source, or Social Media feeds are included. locations: type: array description: >- Locations associated with the profile such as addresses, cities, or countries. items: $ref: '#/components/schemas/SourcedString' images: type: array description: Images associated with the profile. items: $ref: '#/components/schemas/SourcedString' other_fields: type: object description: Miscellaneous fields that do not fit within other defined fields. additionalProperties: $ref: '#/components/schemas/SourcedString' links: type: array description: >- Individuals, entities, or concepts linked to the profile. Includes family relationships (Father, Brother), ownership records (Director, Shareholder), and employee records (Chief Financial Officer). items: $ref: '#/components/schemas/SourcedAffiliation' ID: type: object description: >- Identity-associated fields such as passport numbers, driver's licenses, national IDs. additionalProperties: $ref: '#/components/schemas/SourcedString' documents: type: array description: >- References to digital documents found for this profile. May include corporate registry listings, court and legal documents, public securities filings (SEC), or open source investigation files. items: $ref: '#/components/schemas/UrlInfo' websites: type: array description: >- Websites that are owned by or describe this profile, including corporate websites, personal websites, and blogs. items: $ref: '#/components/schemas/SourcedString' notes: type: array description: Other unstructured transcripts associated with the profile. items: $ref: '#/components/schemas/SourcedString' checklist: $ref: '#/components/schemas/ProfileChecklist' description: >- Watchlist and risk screening states and sources. Contains hit status for each risk feed and detailed breakdown of hits. client_risk_rating: $ref: '#/components/schemas/ClientRiskRating' description: >- Customer Risk Rating (CRR) assessment based on discovered data. Provides overall risk score and contributing factors. sources: type: array description: List of source names that contributed data to this profile. items: type: string example: - OFAC SDN List - World Leaders Database - Reuters source_details: type: array description: >- Details and metadata associated with the sources that contributed data to this profile. items: $ref: '#/components/schemas/SourceDetailElement' score: type: number minimum: 0 maximum: 1 description: >- The Criteria Match Score: a normalized value between 0 and 1 that represents the match to the search parameters. 1.0 = exact match, 0.8-0.99 = partial match, < 0.79 = low confidence match. example: 0.95 match_score_info: $ref: '#/components/schemas/MatchScoreInfo' description: >- Detailed breakdown of the Criteria Match Score for each field provided in the search parameters. review_status: type: string enum: - not_found - unresolved - true_positive - false_positive - suppressed description: >- The review status of the potential match. New matches start as `unresolved`. When the workspace runs Automatic Disposition in Full Auto Mode for the Direct API channel, Minerva can set `true_positive` or `false_positive` before the search response or batch row completes; the applied prediction is returned in `automatic_disposition`. Hint Mode never changes this field: the match stays `unresolved` and the advisory prediction is returned in `disposition_hint`. example: unresolved automatic_disposition: $ref: '#/components/schemas/DispositionAnnotation' description: >- Present only when Automatic Disposition auto-dispositioned this potential match (Full Auto Mode for the Direct API channel) and set `review_status`. Only screened matches, meaning those with at least one flagged feed in `checklist.screen`, are analyzed. Clean matches and workspaces without the feature enabled never carry this field. disposition_hint: $ref: '#/components/schemas/DispositionAnnotation' description: >- Present when the workspace runs an Automatic Disposition outcome in Hint Mode, or when the analysis completed without meeting the configured confidence threshold (an `undetermined` prediction). Advisory only: `review_status` stays `unresolved`, and the annotation is for the integration to interpret in real time. Only screened matches, meaning those with at least one flagged feed in `checklist.screen`, are analyzed. Clean matches and workspaces without the feature enabled never carry this field. reportURL: type: string description: >- URL to the generated PDF report for this profile, if one has been generated. example: https://storage.googleapis.com/... required: - type - name - sources - source_details CustomListFeedStatuses: type: object description: >- Custom-list coverage keyed by canonical public feed name. Omitted when no activated custom lists participated in the entity execution. additionalProperties: $ref: '#/components/schemas/CustomListFeedStatus' FeedStatus: type: object description: >- Acquisition health for one public feed (ENG-3707). `available` means every enabled leg answered; `partial` means at least one answered and at least one degraded; `unavailable` means no enabled leg answered, so a zero-result search for this feed is not evidence of absence. properties: status: type: string enum: - available - partial - unavailable reason: type: string description: Comma-joined _ list of the degraded legs. example: opoint_error,event_registry_error legs: type: array items: $ref: '#/components/schemas/FeedLegStatus' required: - status SourcedName: type: object description: >- Schema for a name, with structured first and last name components and source lineage. properties: value: type: string description: >- The last name (for individuals) or full company name (for organizations). example: Smith first: $ref: '#/components/schemas/SourcedString' description: For individuals only, the first name with source lineage. other_names: type: array description: Middle names, initials, prefixes, and suffixes. items: $ref: '#/components/schemas/SourcedString' sources: type: array description: Source lineage for the last name or full company name. items: $ref: '#/components/schemas/SourcedStringSource' inferred: type: boolean description: >- Indicates whether the value was inferred algorithmically (true) or reported directly from the source. example: false reputation_score: type: integer minimum: 0 maximum: 10 description: Score from 0-10 indicating the reputation of the source. example: 8 trusted: type: boolean description: >- Reports whether the reputation score is at or above the threshold for trusted status. example: true match_score: type: number minimum: 0 maximum: 1 description: >- Score from 0.0-1.0 indicating the closeness of the match between the search criteria and this name. On an entry of a profile's `aliases` array this is that alias's own score, so entries in one array normally differ. Do not read `match_score_info.aliases` as a summary of this array: that value is the aggregate maximum retained as the record's ranking input, and it is not recomputed when the alias list changes, so it can differ from the largest `match_score` present here. example: 0.98 criteria_match_level: $ref: '#/components/schemas/CriteriaMatchLevel' description: Label associated with the match score. matched_query: type: boolean description: >- Present and true on at most one entry of a profile's `aliases` array: the alias whose own text matched the search criteria strictly better than the profile's primary name. Omitted entirely otherwise, including when the primary name matched at least as well, so its absence means no alias out-matched the displayed name. Unrelated to `is_best_match` on a source entry, which is a source-consensus tiebreaker and says nothing about the search criteria. Derived from this array's own scores rather than from `match_score_info.aliases`, so it may be set on a record whose aggregate alias score is lower than this entry's `match_score`. example: true required: - value SourcedGender: type: object description: >- A sourced gender object containing the gender value and source lineage. Gender is normalized to "Male", "Female", "Other", or "Unknown". properties: value: type: string description: The gender value, normalized to Male, Female, Other, or Unknown. enum: - Male - Female - Other - Unknown example: Male sources: type: array description: Array of source lineage objects for this gender field. items: $ref: '#/components/schemas/SourcedStringSource' inferred: type: boolean description: >- Indicates whether the value was inferred algorithmically (true) or reported directly from the source. example: false reputation_score: type: integer minimum: 0 maximum: 10 description: Score from 0-10 indicating the reputation of the source. example: 7 trusted: type: boolean description: >- Reports whether the reputation score is at or above the threshold for trusted status. example: true match_score: type: number minimum: 0 maximum: 1 description: >- Score from 0.0-1.0 indicating the closeness of the match between the search criteria and this gender value. example: 1 criteria_match_level: $ref: '#/components/schemas/CriteriaMatchLevel' description: Label associated with the match score. required: - value SourcedString: type: object description: >- A sourced string object with a consensus value and its source lineage. Minerva applies entity resolution to consolidate data from multiple sources, keeping the original source values and scores in the lineage. properties: value: type: string description: >- The consensus value that best represents the combination of source values discovered during the automated investigation. example: Software Engineer sources: type: array description: >- Array of source lineage objects containing information about each source that reported data for this field. items: $ref: '#/components/schemas/SourcedStringSource' timestamp: $ref: '#/components/schemas/DateObject' description: The timestamp associated with the data. inferred: type: boolean description: >- Indicates whether the value was inferred algorithmically (true) or reported directly from the source. example: false reputation_score: type: integer minimum: 0 maximum: 10 description: >- Score from 0-10 indicating the general reputation and trustworthiness of the consensus value. A value of 7 or above indicates "trusted" status. example: 8 trusted: type: boolean description: >- Indicates whether the value is likely to be ground truth. True when `reputation_score` is 7 or above. example: true match_score: type: number minimum: 0 maximum: 1 description: >- Score from 0.0-1.0 indicating the closeness of the match between the search criteria and this field value. example: 0.95 criteria_match_level: $ref: '#/components/schemas/CriteriaMatchLevel' description: Label associated with the match score. tag: type: string description: >- Additional label to assign the sourced string such as a social media platform. example: LinkedIn required: - value SourcedDate: type: object description: >- A sourced date object containing a consensus date value and source lineage for dates like date of birth or date of incorporation. properties: value: $ref: '#/components/schemas/DateObject' description: The consensus date value. sources: type: array description: Array of source lineage objects for this date field. items: $ref: '#/components/schemas/SourcedDateSource' inferred: type: boolean description: >- Indicates whether the value was inferred algorithmically (true) or reported directly from the source. example: false reputation_score: type: integer minimum: 0 maximum: 10 description: >- Score from 0-10 indicating the general reputation and trustworthiness of the consensus value. example: 9 trusted: type: boolean description: >- Indicates whether the information is likely to be a ground truth, trusted value. example: true match_score: type: number minimum: 0 maximum: 1 description: >- Score from 0.0-1.0 indicating the closeness of the match between the search criteria and this date value. example: 1 criteria_match_level: $ref: '#/components/schemas/CriteriaMatchLevel' description: Label associated with the match score. required: - value ProfileContact: type: object description: >- Contact information for the profile including email addresses and phone numbers. properties: email: type: array description: List of email addresses known for this profile. items: $ref: '#/components/schemas/SourcedString' phone: type: array description: >- List of phone numbers known for this profile. Not guaranteed to be in E.164 format. items: $ref: '#/components/schemas/SourcedString' ProfileMedia: type: object description: >- Media for the profile, including adverse and neutral media URLs and social media accounts. Present when the News, Open Source, or Social Media feeds are included. properties: risk_urls: type: array description: >- URLs that contain relevant AML/financial crimes risk. Articles here are negative in sentiment and associated with one or more of the 28 financial crimes risk categories. items: $ref: '#/components/schemas/UrlInfo' neutral_urls: type: array description: >- URLs that do not contain relevant AML/financial crimes risk. Articles here are not negative in sentiment and not associated with financial crimes risk categories. items: $ref: '#/components/schemas/UrlInfo' usernames: type: array description: >- Social media accounts that the deep learning investigation model associated with this profile. Present when the Open Source or Social Media feeds are included. items: $ref: '#/components/schemas/ProfileSocialUsername' SourcedAffiliation: type: object description: >- Schema for an individual, organization, or concept linked to a profile, such as family connections, ownership records, or employee records. properties: value: type: string description: >- The subject that this affiliation describes, such as a person, organization, or concept. example: Acme Corporation type: $ref: '#/components/schemas/SourcedString' description: >- The way that the source is affiliated with the subject, such as "Father", "Shareholder", or "Chief Financial Officer". sources: type: array description: Source lineage for the affiliation. items: $ref: '#/components/schemas/SourcedStringSource' inferred: type: boolean description: >- Indicates whether the value was inferred algorithmically (true) or reported directly from the source. example: false reputation_score: type: integer minimum: 0 maximum: 10 description: Score from 0-10 indicating the reputation of the source. example: 8 trusted: type: boolean description: >- Reports whether the reputation score is at or above the threshold for trusted status. example: true match_score: type: number minimum: 0 maximum: 1 description: >- Score from 0.0-1.0 indicating the closeness of the match between the search criteria and this affiliation. example: 0.85 criteria_match_level: $ref: '#/components/schemas/CriteriaMatchLevel' description: Label associated with the match score. required: - value UrlInfo: type: object description: >- URL link object with title, source information, and risk classification. Used for documents, news articles, and other web references. properties: url: type: string format: uri description: The URL of the document or article. example: https://www.bbc.com/news/article-123 title: type: string description: The title of the document or article. example: 'Breaking News: Major Development' source_name: type: string description: The name of the source that published the content. example: BBC News snippet: type: string description: >- Small snippet of text from the article, up to 2000 characters. Provides context without requiring full article access. example: The individual was mentioned in connection with... language: type: string description: ISO2 code of the language of the text, or blank if unknown. example: en flags: type: object description: >- Risk and sentiment classification flags from deep learning inference on the article text. properties: sentiment: type: array description: >- Sentiment classification with confidence level. Values include "Positive", "Neutral", or "Negative" followed by confidence (Low/Medium/High). items: type: string example: - Negative (High) risk: type: array description: >- One or more of 28 different types of financial crimes risk, with confidence level. Examples: "Money Laundering (High)", "Fraud/Bribery/Corruption (Medium)", "Other (Non-Financial) (Low)". items: type: string example: - Money Laundering (High) - Fraud/Bribery/Corruption (Medium) http_status_code: type: integer description: >- The HTTP status received by the test probe to determine content availability. example: 200 date_time_published: type: string description: Datetime string of when the article was published. Empty if unknown. example: '2024-01-15T10:30:00Z' required: - url - title ProfileChecklist: type: object description: >- Watchlist and risk screening states and sources. Contains the hit status for various risk feeds and detailed breakdown of each hit. properties: screen: $ref: '#/components/schemas/FeedScreen' description: Hit status for each feed (true for hit, false for clear). hits: $ref: '#/components/schemas/FeedHits' description: Lists of sources that Minerva found as hits for each feed. hits_info: type: array description: >- Detailed breakdown of hits with original source values and match scores for each attribute. items: $ref: '#/components/schemas/ScreeningHitInfo' required: - screen - hits - hits_info ClientRiskRating: type: object description: >- Customer Risk Rating (CRR) assessment on the profile based on discovered data. Provides overall risk score and breakdown of contributing factors. properties: score: type: number minimum: 0 maximum: 1 description: >- The customer risk rating score, normalized from 0.0-1.0. Higher values indicate higher risk. example: 0.75 label: type: string enum: - High - Medium - Low - None description: The risk rating label associated with the score. example: High factors: type: array description: >- List of criteria factors with their weights and values that comprise the total CRR analysis. items: $ref: '#/components/schemas/ClientRiskRatingFactor' required: - score - label - factors SourceDetailElement: type: object description: Metadata about a source providing additional information. properties: name: type: string description: The name of the source. example: OFAC SDN List source_feed: type: string description: The screening feed the source is associated with. example: Sanctions flagged_feeds: type: array description: The screening feeds that the source flagged. items: type: string example: - Sanctions - PEP urls: type: array description: URLs associated with the source. items: $ref: '#/components/schemas/UrlInfo' description: type: string description: Description of the source or explanation of why it has no URLs. example: Official US Treasury sanctions database inferences: type: array description: Inferences made from the source. items: $ref: '#/components/schemas/SourceDetailInference' required: - name - source_feed - flagged_feeds - urls - description - inferences MatchScoreInfo: type: object description: >- Detailed breakdown of the Criteria Match Score for each field provided in the search parameters. additionalProperties: $ref: '#/components/schemas/MatchScoreInfoField' example: name: score: 0.98 criteria_match_level: exact verified: true country: score: 0.85 criteria_match_level: close verified: true DispositionAnnotation: type: object description: >- AI disposition annotation produced by [Automatic Disposition](/automatic-disposition-guide) analysis for a screened potential match. Returned as `automatic_disposition` when workspace policy allowed the prediction to set `review_status` (Full Auto Mode), or as `disposition_hint` when the analysis is advisory only (Hint Mode, or a completed analysis that did not reach the configured confidence threshold). Both fields are omitted for matches screened without automatic disposition. properties: prediction: type: string enum: - true_positive - false_positive - undetermined description: >- Model disposition for the potential match against the searched subject. `undetermined` appears only on `disposition_hint`, when the analysis completed without reaching a configured confidence threshold. example: false_positive confidence: type: number minimum: 0 maximum: 1 description: Model confidence in the prediction. example: 0.95 analysis_status: type: string enum: - completed - failed description: >- Whether the disposition analysis ran to completion for this match. When `failed`, the match is left `unresolved` for normal manual review. example: completed rationale: type: string description: >- Short natural-language explanation of the prediction for analyst review. example: >- The searched subject's occupation and country conflict with the listed person. evidence_refs: type: array description: >- References to the match payload fields and articles the model relied on. items: type: object score_summary: type: object description: Per-field score breakdown produced by the disposition analysis. risk_flags: type: array description: Risk signals the analysis surfaced while reviewing the evidence. items: type: string signature_version: type: string description: >- Automatic Disposition prompt/signature version used for the analysis. source: type: string description: >- Screening channel that produced the annotation. Always `direct_api` for Direct API searches. example: direct_api error: type: object description: >- Bounded error metadata, present only when the analysis could not complete cleanly for this match. properties: code: type: string message: type: string retryable: type: boolean CustomListFeedStatus: type: object description: >- Custom-list coverage for one requested public feed. Partial or unavailable states prevent consumers from interpreting an empty result as an authoritative clean screening. properties: status: type: string enum: - available - partial - unavailable reason: type: string enum: - custom_lists_not_ready - custom_lists_unavailable - custom_list_routing_metadata_unavailable - custom_list_routing_generation_mismatch - custom_list_fanout_deadline_exceeded - custom_list_shard_unavailable effective_versions: type: array items: $ref: '#/components/schemas/CustomListExecutionLineage' required: - status FeedLegStatus: type: object description: >- One provider leg of a public feed and what it actually did. `empty` is the only outcome that licenses a zero-result answer for that source; `error`, `timeout` and `skipped` mean coverage was degraded. properties: leg: type: string description: >- Stable leg identity (opoint, event_registry, article_search, agentic_adm, integration). example: opoint outcome: type: string enum: - ok - empty - error - timeout - skipped - disabled documents: type: integer minimum: 0 elapsedMs: type: integer minimum: 0 description: Omitted for legs that never issued a request. detail: type: string description: >- Optional refinement of a degraded outcome, e.g. bulkhead_wait for a timeout spent queueing behind the provider's concurrency limit. required: - leg - outcome - documents SourcedStringSource: type: object description: >- Single unit of data lineage for a sourced string value. Each source contributes to the value consensus. allOf: - $ref: '#/components/schemas/SourceFields' - type: object properties: value: type: string description: The value reported by this source. example: John Smith required: - value CriteriaMatchLevel: type: string enum: - exact - close - loose - none description: >- Label for a match score that describes how close the match is. Thresholds: exact (>= 0.98), close (>= 0.85), loose (>= 0.75), none (< 0.75). example: close DateObject: type: object description: A date object containing year, month, and day components. properties: year: type: integer description: >- The year component of the date. Always present when the date is known. A 4 digit integer for a calendar year. example: 1984 month: type: integer minimum: 1 maximum: 12 description: >- The integer corresponding to the calendar month (1-12). May not be present if the month is not known. example: 6 day: type: integer minimum: 1 maximum: 31 description: >- The integer corresponding to the calendar day. May not be present if the day is not known. example: 15 required: - year SourcedDateSource: type: object description: Single unit of data lineage for a sourced date value. allOf: - $ref: '#/components/schemas/SourceFields' - type: object properties: value: $ref: '#/components/schemas/DateObject' description: The date value reported by this source. required: - value ProfileSocialUsername: type: object description: >- Social media username associated with the profile, discovered through deep learning investigation. properties: value: type: string description: The social media username. example: john_smith_official tag: type: string description: The name of the social media platform. example: Twitter sources: type: array description: Sources that contributed to the consensus value. items: $ref: '#/components/schemas/SourcedString' required: - value FeedScreen: type: object description: >- Hit status for each feed that was screened. True indicates a hit/finding, false indicates clear/no hits. properties: Sanctions: type: boolean description: >- True if the profile is listed on an international sanctions list (OFAC SDN, HMT, OSFI Consolidated, and others). PEP: type: boolean description: >- True if profile is a domestic PEP, foreign PEP, RCA of a PEP, head of a state-owned corporation, or HIO. Criminal: type: boolean description: >- True if profile is determined to be a criminal actor based on watchlists (e.g., FBI Terrorism List) or inference. Legal: type: boolean description: True if profile has high risk legal cases involving it. News: type: boolean description: >- True if profile has high risk adverse media articles (negative sentiment + adverse media risk categories). Open Source: type: boolean description: True if open source investigation found relevant hits. Social Media: type: boolean description: True if social media investigation found relevant hits. Registries: type: boolean description: True if corporate registry searches found relevant hits. Ownership: type: boolean description: True if ownership/beneficial ownership searches found relevant hits. Offshore: type: boolean description: True if offshore entity databases found relevant hits. FeedHits: type: object description: >- Lists of source names that were hit for each feed. Only present for feeds where screen value is true. properties: Sanctions: type: array items: type: string example: - OFAC SDN List - EU Consolidated List PEP: type: array items: type: string example: - World Leaders Database Criminal: type: array items: type: string example: - FBI Most Wanted Legal: type: array items: type: string example: - PACER News: type: array items: type: string example: - Reuters - BBC News Open Source: type: array items: type: string Social Media: type: array items: type: string Registries: type: array items: type: string Ownership: type: array items: type: string Offshore: type: array items: type: string ScreeningHitInfo: type: object description: >- Detailed breakdown of a screening hit, with original source values and match scores for each attribute. Helps distinguish potential match identifiers across risk sources. properties: source: type: string description: The name of the source that this hit was triggered from. example: OFAC SDN List feed: type: string description: The Minerva data feed that the source belongs to. enum: - Sanctions - PEP - News - Legal - Criminal example: Sanctions name: $ref: '#/components/schemas/ScreeningHitInfoField' description: Match attributes of the name that was hit upon from this source. occupation: $ref: '#/components/schemas/ScreeningHitInfoField' description: >- The job title reported by the hit source. Present for individual profiles only. Match score is 0.0 if not provided in search parameters. organization: $ref: '#/components/schemas/ScreeningHitInfoField' description: >- The organization reported by the hit source. Present for individual profiles only. Match score is 0.0 if not provided in search parameters. nationality: $ref: '#/components/schemas/ScreeningHitInfoField' description: >- The nationality reported by the hit source. Match score is 0.0 if country not provided in search parameters. date: $ref: '#/components/schemas/ScreeningHitInfoField' description: >- The date reported by the hit source (format: YYYY-MM-DD, YYYY, or YYYY-MM). Match score is 0.0 if date not provided in search parameters. locations: type: array description: >- Locations reported by the hit source. May contain address, city, state, or country. The match score is 0.0 when the search parameters contain no location. items: $ref: '#/components/schemas/ScreeningHitInfoField' required: - source - feed - name ClientRiskRatingFactor: type: object description: >- A single factor that contributed to an overall client risk rating (CRR) score. properties: weight: type: number minimum: 0 maximum: 1 description: >- The weight applied to the value when creating the consolidated weighted score. example: 0.15 value: type: number minimum: 0 maximum: 1 description: The value of the factor calculated, before weighting was applied. example: 0.8 code: type: integer description: >- Primary key mapping of the factor to the total list of possible criteria. Guaranteed to remain the same over time. example: 1 label: type: string description: >- Human-readable context about what this factor represents in the weighting scheme. example: Sanctions List annotation: type: string description: >- Additional notes providing further description about the factor value. example: Listed on OFAC SDN required: - weight - value - code - label SourceDetailInference: type: object description: >- Details regarding an inference made from a source, such as PEP or Criminal inference. properties: feed: type: string description: The screening feed that the inference flagged for. example: PEP reason: type: string description: The reason the inference was made. example: Matched regex pattern for political position url: type: string description: URL linking to the source of the inference data. example: https://example.com/article field: type: string description: The field the inference was made on. example: Notes context: type: string description: Snippet of text providing context for the inference. example: The individual served as Minister of... required: - feed - reason - url - field - context MatchScoreInfoField: type: object description: Match score information for a single search parameter field. properties: score: type: number minimum: 0 maximum: 1 description: >- Match score from 0.0-1.0 where 1.0 represents a perfect match and 0.0 represents no match. example: 0.95 criteria_match_level: $ref: '#/components/schemas/CriteriaMatchLevel' description: >- String label corresponding to the score: "exact" (>= 0.98), "close" (>= 0.85), "loose" (>= 0.75), "none" (< 0.75). verified: type: boolean description: >- True if the match meets verification requirements: source reputation_score >= 7 (trusted) AND criteria_match_level is at least "close". example: true required: - score - criteria_match_level - verified CustomListExecutionLineage: type: object description: >- The effective custom-list version and shard placement used for one feed execution. These values reflect any routing-generation refresh performed by the worker rather than the stale submit-time manifest. properties: list_id: type: string list_version_id: type: string routing_generation: type: integer format: int64 shard_index: type: integer format: int32 required: - list_id - list_version_id SourceFields: type: object description: Fields that are shared by all source lineage records. properties: source: type: string description: The human readable name of the source. example: OFAC SDN List feed: type: string description: >- The Minerva data feed this source belongs to. One of the supported Minerva data feeds. enum: - Internal - Sanctions - PEP - Criminal - Legal - Offshore - Ownership - Registries - Social Media - News - Open Source example: Sanctions timestamp: $ref: '#/components/schemas/DateObject' description: >- The timestamp associated with when the data was collected or reported. inferred: type: boolean description: >- Indicates whether the value was inferred algorithmically (true) or reported directly from the source. Inferred values are down-weighted in the consensus algorithm. example: false reputation_score: type: integer minimum: 0 maximum: 10 description: >- Score from 0-10 indicating the reputation of the source. A value of 7 or above indicates "trusted" status where the source is highly accredited. example: 8 trusted: type: boolean description: >- Reports whether the reputation score is at or above the threshold (7) for the source to be considered trusted. example: true match_score: type: number minimum: 0 maximum: 1 description: >- Score from 0.0-1.0 indicating the closeness of the match between the search criteria and this source value. example: 0.92 criteria_match_level: $ref: '#/components/schemas/CriteriaMatchLevel' description: Label associated with the match score. is_best_match: type: boolean description: >- Present and true on the source entry whose assertion won the value consensus for this field, i.e. the source that supplied the displayed value. Omitted entirely otherwise. This is a source-consensus tiebreaker and says nothing about the search criteria: for "which name did the query actually match", see `matched_query` on an entry of a profile's `aliases` array. example: true ScreeningHitInfoField: type: object description: >- Information about the match for a single field from a potential screening hit. properties: value: type: string description: The value of the field that was matched. example: John Smith match_score: type: number minimum: 0 maximum: 1 description: >- The computed match score between the query parameter and the original source value. example: 0.95 criteria_match_level: $ref: '#/components/schemas/CriteriaMatchLevel' description: The label associated with the match score. required: - value - match_score - criteria_match_level 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. UserTokenAuth: type: apiKey in: header name: x-user-token description: >- The temporary Firebase client user token, generated by the frontend and validated on the server side. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.