---
title: "Report how a screened transaction ended"
method: POST
path: "/transaction-screenings/{transaction_screening_id}/outcome"
tags: ["Screenings"]
---

# Report how a screened transaction ended

`POST /transaction-screenings/{transaction_screening_id}/outcome`

## Request

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

Tells OZAV how the transaction ended: the risk was real, the flag was wrong, or the transaction
completed, was reversed or charged back. An outcome is recorded once: sending the same outcome and
note again returns the screening (safe to retry), a different one returns `409 OUTCOME_ALREADY_RECORDED`.
Outcomes are how OZAV measures and improves its rules. Free.

## Path parameters

- `transaction_screening_id` string, required

## Request body

- DecisionOutcomeRequest
  - `outcome` 'confirmed_risk' | 'false_positive' | 'completed' | 'reversed' | 'chargeback', required: - `confirmed_risk` - the risk was real. - `false_positive` - the flag was wrong. - `completed` - the operation went ahead and completed normally. - `reversed` - the operation was reversed or refunded. - `chargeback` - the operation ended in a chargeback.
  - `note` string: Optional free text.

## Response `200`

The screened transaction with its outcome.

- TransactionScreening
  - `object` 'transaction_screening', required
  - `id` string, required: The transaction screening id (`ozav_txs_...`).
  - `livemode` boolean, required
  - `external_id` string, nullable
  - `direction` 'inbound' | 'outbound', required
  - `amount_usd` string, required
  - `currency` string, nullable
  - `amount` string, nullable
  - `counterparty_country` string, nullable
  - `occurred_at` string, date-time, required
  - `effect` 'allow' | 'review' | 'deny', required: The worst rule that fired; `allow` when none did. Advice only: OZAV never blocks the transaction, the decision is yours.
  - `score` integer, required: The sum of the rules' scores, capped at 100.
  - `reasons` object[], required
    - `code` 'high_risk_country' | 'large_amount' | 'velocity_24h' | 'structuring_24h' | 'volume_spike' | 'prior_confirmed_risk', required
    - `effect` 'review' | 'deny', required
    - `score` integer, required: 0 when the rule is cleared by your own outcome (see `cleared_by`).
    - `severity` 'low' | 'medium' | 'high', required
    - `detail` string, required
    - `cleared_by` string, nullable: The screening you reported as `false_positive` for this customer in the last 90 days, which clears this rule for this customer up to the size you labeled. A cleared rule still shows here, with score 0, and does not count toward `effect`. Only `large_amount`, `velocity_24h` and `volume_spike` can be cleared.
    - `related_screening` string, nullable: For `prior_confirmed_risk`, the screening you reported as `confirmed_risk`.
  - `rule_version` string, required
  - `outcome` 'confirmed_risk' | 'false_positive' | 'completed' | 'reversed' | 'chargeback' | 'null', nullable: How the transaction ended, as you reported it with `POST /transaction-screenings/{transaction_screening_id}/outcome`; `null` until then.
  - `outcome_note` string, nullable
  - `outcome_at` string, date-time, nullable
  - `created_at` string, date-time, required

## 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).
- `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)