---
title: "Confirm a match or mark it a false positive, with a reason"
method: POST
path: "/api/v1/screening/matches/{id}/decision"
tags: ["Screening"]
---

# Confirm a match or mark it a false positive, with a reason

`POST /api/v1/screening/matches/{id}/decision`

## Request

- Base URL: `https://api.korala.ai`
- URL: `https://api.korala.ai/api/v1/screening/matches/{id}/decision`
- Auth: one of:
  - API key in header `X-API-Key`
  - `bearer` (a scheme the document does not define)

An organization owner or admin, signed in to the dashboard. API keys and members are refused (403).

## Path parameters

- `id` string, required

## Headers

- `X-Korala-Mode` 'live' | 'test'
- `Idempotency-Key` string, required

## Request body

- DecideScreeningMatchDto
  - `decision` 'confirmed' | 'false_positive', required
  - `reason` string, required: Why, in words. Trimmed; blank or whitespace only is refused.

## Response `200`

- ScreeningRunDto
  - `id` string, uuid, required
  - `status` 'clear' | 'possible_match' | 'match' | 'incomplete' | 'error', required
  - `incomplete` boolean, required: The screening was not complete (see incompleteReasons). Nothing found in an incomplete run is status incomplete, never clear.
  - `incompleteReasons` string[], required: source_missing, source_stale, source_attention, source_dropped_entries, source_reindex_pending, candidates_capped (the sanctions pool), pep_candidates_capped (the PEP pool), pep_lookback_beyond_list (the PEP look-back is longer than a PEP list goes back), name_terms_capped, name_without_tokens.
  - `errorCode` string, nullable, required
  - `trigger` 'check_step' | 'api', required
  - `sandbox` boolean, required
  - `sessionId` string, uuid, nullable, required
  - `participantId` string, uuid, nullable, required
  - `riskSubjectId` string, uuid, nullable, required
  - `workflowRunId` string, uuid, nullable, required
  - `sources` ScreeningRunSourceDto[], required
    - `key` string, required
    - `sourceId` string, uuid, nullable, required
    - `versionId` string, uuid, nullable, required: The list version searched; null when there was none.
    - `publishedAt` string, date-time, nullable, required
    - `missing` boolean, required: Not searched: unknown, off, or never loaded.
    - `droppedEntries` number, required: Entries the list version dropped because its parser could not read them. Any makes the run incomplete.
    - `droppedTerms` number, required: Terms over 300 characters the searched version did not index, counted over the entries that version indexed itself: those it added or changed, or every listed entry when it rebuilt the list's terms for a new term builder. Terms left out of an entry an earlier version indexed, and this one kept unchanged, are not counted. Recorded only: no name a subject can be screened under is that long.
    - `termBuilderVersion` number, nullable: The term builder that indexed the list version searched: from 3 the index finds names within one letter. Null when the list was not searched; absent on runs recorded before the field was added.
    - `reindexPending` boolean: The version searched was indexed by an older term builder and its index has not been rebuilt yet: names one letter off were not searched on it, and the run is incomplete (source_reindex_pending). Absent on runs recorded before the field was added.
    - `stale` boolean, required
    - `staleReasons` string[], required
    - `attention` string, nullable, required
  - `policy` ScreeningRunPolicyDto, required
    - `reviewScore` number, required
    - `matchScore` number, required
    - `scorerVersion` string, required
    - `pepLookbackMonths` number: Runs that screened the PEP list: the months after leaving office a person still counted as a PEP.
  - `listKinds` string[], required: The kinds of list screened: sanctions, pep, or both.
  - `riskSource` string, required: The risk source of the first kind screened (sanctions when screened, otherwise pep); riskSources has each.
  - `riskSources` ScreeningRiskSourceDto[], required: Each kind of list as the evidence it records: screening.sanctions and screening.pep, each under its own source.
    - `fact` 'screening.sanctions' | 'screening.pep', required
    - `riskSource` string, required: Accept it in a policy input for this fact.
  - `candidateCount` number, required: Listed entries scored, at most 200. Entries whose kind, dates of birth or nationalities keep them below reviewScore are set aside unscored and not counted.
  - `topScore` number, nullable, required: The highest score of the scored entries, or null when none was scored. Entries set aside as unable to reach review are not in it.
  - `createdAt` string, date-time, required
  - `updatedAt` string, date-time, required
  - `matches` ScreeningMatchDto[], required
    - `id` string, uuid, required
    - `entryId` string, uuid, required
    - `source` string, required: The list key.
    - `listVersionId` string, uuid, required
    - `sourceEntryId` string, required: The publisher's own id for the entry.
    - `entityType` string, required
    - `listedName` string, required: The entry’s primary name as listed.
    - `matchedName` string, nullable, required: The listed name (primary or alias) that matched.
    - `listedOn` string, nullable, required
    - `programmes` string[], required: Sanctions lists: the programmes. The PEP list: the categories of the positions, or family_member.
    - `listKind` 'sanctions' | 'pep', required: The kind of list.
    - `pep` ScreeningMatchPepDto, required
      - `standing` 'pep' | 'former_pep' | 'family_member' | 'none', required: Where the entry stood on the day of the run: a PEP (in office, or out of office for less than the look-back), a former PEP, a family member of a PEP, or none: a relative whose related PEPs are no longer PEPs (the match and its relation are shown; screening.pep records no family member).
      - `flags` string[], required: position_dates_unknown: no position states when it was held, so the person is treated as a PEP.
      - `lookbackMonths` number, required
      - `lastHeldUntil` string, nullable, required: A former PEP: the latest end date of any position.
      - `role` 'pep' | 'family_member', required
      - `categories` string[], required
      - `positions` ScreeningPepPositionDto[], required
        - `category` string, required: legislature, ministers, head_of_state, head_of_government, central_bank, top_court_judges, ambassadors, io (international organisation), local_regional_heads, soe_heads, military_chiefs, party_leaders, ...
        - `title` string, nullable, required: The position as the source names it, when it does.
        - `positionId` string, nullable, required: The Wikidata item of the position, when there is one.
        - `country` string, nullable, required: ISO 3166-1 alpha-2; null for an international organisation.
        - `start` string, nullable, required: YYYY, YYYY-MM or YYYY-MM-DD, as the source states it.
        - `end` string, nullable, required
        - `current` boolean, required: The source says it is held now.
        - `source` string, nullable, required: The roster that states it; null for Wikidata.
      - `relatedPeps` ScreeningRelatedPepDto[], required: A family member: the PEPs it is related to.
        - `sourceEntryId` string, required: The PEP's entry id on the same list.
        - `name` string, required
        - `relation` string, required: What the family member is to the PEP: spouse, child, father, mother or sibling.
        - `positions` ScreeningPepPositionDto[]: The related PEP's positions that make the relative a family member (a sibling: head of state or government, minister or deputy minister only), from which its standing on the day of the run is judged.
          - `category` string, required: legislature, ministers, head_of_state, head_of_government, central_bank, top_court_judges, ambassadors, io (international organisation), local_regional_heads, soe_heads, military_chiefs, party_leaders, ...
          - `title` string, nullable, required: The position as the source names it, when it does.
          - `positionId` string, nullable, required: The Wikidata item of the position, when there is one.
          - `country` string, nullable, required: ISO 3166-1 alpha-2; null for an international organisation.
          - `start` string, nullable, required: YYYY, YYYY-MM or YYYY-MM-DD, as the source states it.
          - `end` string, nullable, required
          - `current` boolean, required: The source says it is held now.
          - `source` string, nullable, required: The roster that states it; null for Wikidata.
      - `sources` string[], required: wikidata and the official rosters the entry comes from.
      - `wikidataId` string, nullable, required
    - `score` number, required
    - `factors` ScreeningFactorDto[], required
      - `code` string, required
      - `points` number, required
      - `cap` number
      - `detail` string: About the listed entry.
    - `decision` 'pending' | 'confirmed' | 'false_positive', required
    - `decidedBy` string, nullable, required
    - `decidedAt` string, date-time, nullable, required
    - `decisionReason` string, nullable, required

## Other responses

- `400`: Malformed UUID in path parameter (`id`).

---

[API](https://skmtc.dev/korala/apis/korala-public-api.md) · [All operations](https://skmtc.dev/korala/apis/korala-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/korala/apis/korala-public-api/revisions/5c4d7810c507?raw)