> ## Documentation Index
> Fetch the complete documentation index at: https://stytch.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Override verdict reasons

> Customizing the action associated with a verdict reason.

## Overview

For every fingerprint lookup, Device Fingerprinting recommends a specific [verdict action](https://stytch.com/docs/fraud-risk/device-fingerprinting/verdict/overview.md). You can override the default action to customize the recommendations based on your application and traffic.

* This is most useful for customizing [Protected Auth](https://stytch.com/docs/fraud-risk/device-fingerprinting/protected-auth.md) decisioning.
* If you are directly integrating with the Device Fingerprinting API, you can also use verdict reason overrides to change decisioning logic without needing to write and deploy new backend code.

### Example

The `VIRTUAL_MACHINE` warning flag results in a `CHALLENGE` by default,
but you might expect many legitimate users to be using an enterprise browser (that runs in a virtual machine). You can override verdict reasons so that `VIRTUAL_MACHINE` maps to an `ALLOW` verdict instead.

> [!NOTE]
>
> See [Reference guides](https://stytch.com/docs/fraud-risk/development/warning-flags.md) for a full list of all verdict reasons or use the [Get Verdict Reasons endpoint](https://stytch.com/docs/api-reference/fraud/api/get-verdict-reasons.md).

***

## Prerequisites

* An existing Stytch project in the [Dashboard](https://stytch.com/dashboard).
* The `project_id` and `secret` for your project's Test environment. These can be found under your project's *Project ID & API keys* section in the [Dashboard](https://www.stytch.com/dashboard).
* Device Fingerprinting [enabled for your project](https://stytch.com/dashboard/dfp-rules).
  * If you don't have Device Fingerprinting enabled, you can [request access here](https://offers.stytch.com/dfp-30-day-trial?utm_source=stytch_docs\&utm_medium=direct\&utm_content=dfp_30_day_trial).

## Steps

**1. Select which verdict reason to override**

You will need the verdict reason and action to associate with it.

* See [Reference guides](https://stytch.com/docs/fraud-risk/development/overview.md) for warning flags (verdict reasons).
* Or use the [Get Verdict Reasons endpoint](https://stytch.com/docs/api-reference/fraud/api/get-verdict-reasons.md).

For the chosen verdict reason, you can decide the new action: `ALLOW`, `BLOCK`, or `CHALLENGE`.

**2. Call Set Verdict Reason Override**

Call the [Set Verdict Reason Override](https://stytch.com/docs/api-reference/fraud/api/set-verdict-reason-override.md) endpoint:

```bash theme={null}
curl --request POST \
  --url https://telemetry.stytch.com/v1/verdict_reasons/override \
  -u '${projectId}:${secret}' \
  -H 'Content-Type: application/json' \
  --data '{
      "verdict_reason": "VIRTUAL_MACHINE",
      "override_action": "ALLOW",
      "description": "Allow instead of challenge VMs because we expect lots of legitimate VM users"
  }'
```

This example sets `VIRTUAL_MACHINE` to `ALLOW` instead of the default reason.

**3. Review the new override**

You can use the [Get Verdict Reasons endpoint](https://stytch.com/docs/api-reference/fraud/api/get-verdict-reasons.md) to confirm your change:

```bash theme={null}
curl --request POST \
  --url https://telemetry.stytch.com/v1/verdict_reasons/list \
  -u '${projectId}:${secret}' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

The resulting list will contain an entry showing the override for `VIRTUAL_MACHINE`:

```json theme={null}
{
    "verdict_reason_overrides": [
        # ...
        {
            "verdict_reason": "VIRTUAL_MACHINE",
            "default_action": "CHALLENGE",
            "override_action": "ALLOW",
            "override_created_at": "2025-01-02T03:04:05Z",
            "description": "Allow instead of challenge VMs because we expect lots of legitimate VM users"
        }
    ]
}
```

> [!NOTE]
>
> The response also includes `verdict.verdict_reason_overrides` that contains information about overrides applied to a specific lookup.

**4. Delete the override**

To delete the override, call the [Set Verdict Reason Override endpoint](https://stytch.com/docs/api-reference/fraud/api/set-verdict-reason-override.md) with an action of `NONE`:

```bash theme={null}
curl --request POST \
  --url https://telemetry.stytch.com/v1/verdict_reasons/override \
  -u '${projectId}:${secret}' \
  -H 'Content-Type: application/json' \
  --data '{
      "verdict_reason": "VIRTUAL_MACHINE",
      "override_action": "NONE"
  }'
```
