---
title: "Decide a screening hit"
method: PATCH
path: "/screenings/{screening_id}/hits/{hit_id}"
tags: ["Screenings"]
---

# Decide a screening hit

`PATCH /screenings/{screening_id}/hits/{hit_id}`

## Request

- Base URL: `https://developers.ozav.io/v2`
- URL: `https://developers.ozav.io/v2/screenings/{screening_id}/hits/{hit_id}`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Marks one hit of a screening as `false_positive` or `confirmed`, with a reason.

**Decide once.** The decision is kept by the hit's fingerprint (list entry, strength, listed name)
and reused by the following screenings of the same subject that hit the same entry - when the
subject is identifiable: a `customer_id`, or a person with `date_of_birth`. Without that (a
person without date of birth, or an inline business), the decision applies to this screening
only, because a bare name matches every homonym. A changed list entry starts `open`.

The screening you decide on keeps the `suggested_decision` it was created with; its
`matches[].status` shows the decision. Your decision is the final one, on any hit, sanctions
lists included. When OZAV compliance has also reviewed a hit, its decision shows until you
decide. Screenings created before hit decisions existed return 422 `HIT_NOT_DECIDABLE`: screen
the subject again and decide on the new screening.
Sending the decision the hit already has (by you) returns 200 with the current state and
records nothing new.

## Path parameters

- `screening_id` string, required
- `hit_id` string, required

## Request body

- ScreeningHitDecisionRequest
  - `decision` 'false_positive' | 'confirmed', required: - `false_positive` - the hit is not the subject. - `confirmed` - the hit is the subject.
  - `reason` string, required: Why - kept for audit (at least 10 characters, no NUL). Do not put personal data here.

## Response `200`

The hit with its effective decision.

- ScreeningHit
  - `id` string, required: The hit id (`hit_...`).
  - `object` 'screening_hit', required: Always the literal `screening_hit`.
  - `screening_id` string, required: The screening the decision was made on (`ozav_scr_...`).
  - `category` 'sanctions_list' | 'pep_list', required: - `sanctions_list` - a sanctions-list hit. - `pep_list` - a PEP-register hit.
  - `status` 'open' | 'false_positive' | 'confirmed', required: The effective decision now (yours prevails over OZAV's).
  - `decided_by` 'you' | 'ozav' | 'null', nullable: `you` or `ozav`.
  - `reason` string, nullable: The reason of the effective decision.
  - `decided_at` string, date-time, nullable: When the effective decision was made.

## Other responses

- `400`: The request is invalid.
- `401`: Missing or invalid API key.
- `403`: The organization lacks the entitlement (code ENTITLEMENT_REQUIRED) or the key lacks the scope (code INSUFFICIENT_SCOPE). On money-moving requests (POST /transfers, POST /wallets/{wallet_id}/transfers) a compliance hold on the customer answers with code COMPLIANCE_HOLD: the hold is reviewed and lifted on OZAV's side; retrying does not clear it. When the only hold is a pause until pending onboarding documents are received, a withdrawal answers CUSTOMER_DOCUMENTS_PENDING instead: send what `requirements` on GET /customers/{id} lists; OZAV lifts the pause after reviewing it. On OZAV Services (live without the platform's KYB), any API outside decisions, screenings, lists and self-custody wallets answers with code PRODUCTION_NOT_ACTIVATED.
- `404`: The resource does not exist, is not visible to the caller, or the id was malformed for this position (see "Resource ids" under Errors). These share one status; `code` and `message` tell them apart.
- `409`: Conflict (e.g. IDEMPOTENCY_KEY_REUSED).
- `422`: The request is well-formed but cannot be fulfilled - e.g. a `rail` that is not served (see `Rail.x-ozav-rail-availability`).
- `503`: A dependency OZAV needs (storage, a resource lookup) could not be reached, so OZAV fails closed rather than guess. Safe to retry with the same `Idempotency-Key` where the operation accepts one.

---

[API](https://skmtc.dev/ozav/apis/ozav-api.md) - [All operations](https://skmtc.dev/ozav/apis/ozav-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ozav/apis/ozav-api/revisions/4133dc2109d7?raw)