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

# Evaluation Overrides

> Evaluation overrides let you temporarily bypass fraud rules or spend control limits for a specific customer, account, card, or transaction.

## Overview

Synctera's platform evaluates every transaction against a set of risk rules — fraud checks and [spend controls](/v2/docs/spend-controls-guide). In most cases these automated evaluations produce the right outcome, but there are situations where a human reviewer determines that a decline or case was a false positive and the customer should be allowed to proceed.

**Evaluation overrides** give you a controlled way to do this. An override tells the platform: *"for this customer (and optionally this account, card, or spend control), skip the specified evaluation for a defined period of time."*

Key characteristics:

* **Scoped** — each override is tied to a `customer_id` and can optionally be narrowed to a specific `account_id`, `card_id`, `spend_control_id`, or `transaction_id`.
* **Typed** — the `type` field indicates which category of evaluation to bypass: `FRAUD` (fraud-rule evaluation) or `SPEND_CONTROL` (spend-control limit evaluation).
* **Time-bound** — every override has an `active_at` timestamp and an optional `expires_at` timestamp so overrides don't remain in effect indefinitely.
* **Auditable** — a `reason` (minimum 3 characters) is required on creation, providing a clear audit trail for compliance review.

### When to use evaluation overrides

Common scenarios include:

* **False-positive fraud decline** — A customer contacts support because a legitimate transaction was blocked by a fraud rule. After review, an agent creates a `FRAUD` override so the customer can retry.
* **Temporary spend-control exception** — A customer needs to make a one-time large purchase that exceeds their normal spend-control limit. A `SPEND_CONTROL` override allows the transaction without permanently changing the spend control.
* **Transaction-specific bypass** — An override scoped to a `transaction_id` allows a single previously-declined transaction to be retried.

## Prerequisites

This guide assumes you have:

* Created a [personal customer](/v2/docs/create-a-personal-customer) or [business customer](/v2/docs/create-a-business)
* Familiarity with [spend controls](/v2/docs/spend-controls-guide) (if creating `SPEND_CONTROL` overrides)

You should also be familiar with:

* [Need to Know — Environments](/v2/reference/need-to-know#environments)
* [Need to Know — Authentication](/v2/reference/need-to-know#authentication)

## The evaluation override object

An evaluation override contains the following key fields:

| Field              | Description                                                      |
| ------------------ | ---------------------------------------------------------------- |
| `id`               | Unique identifier (read-only, assigned on creation).             |
| `customer_id`      | **Required.** The customer the override applies to.              |
| `type`             | The evaluation category to override: `FRAUD` or `SPEND_CONTROL`. |
| `reason`           | **Required.** Why the override was created (min 3 characters).   |
| `active_at`        | When the override takes effect.                                  |
| `expires_at`       | When the override expires (optional).                            |
| `account_id`       | Optionally scope the override to a specific account.             |
| `card_id`          | Optionally scope the override to a specific card.                |
| `spend_control_id` | Optionally scope the override to a specific spend control.       |
| `transaction_id`   | Optionally scope the override to a specific transaction.         |

```json theme={"system"}
{
  "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "customer_id": "5f4ff599-7c29-4f69-a3d9-e103e151afbd",
  "account_id": "30044785-ddb0-4a51-be1c-402bd4ba2b2b",
  "type": "FRAUD",
  "reason": "False positive - customer confirmed transaction is legitimate.",
  "active_at": "2024-01-01T00:00:00.000Z",
  "expires_at": "2024-12-31T23:59:59.000Z",
  "creation_time": "2024-01-01T00:00:00.000Z",
  "last_updated_time": "2024-01-01T00:00:00.000Z"
}
```

See the [API reference](/v2/reference/listevaluationoverrides) for the full request and response schemas.

## Managing evaluation overrides

<Steps>
  <Step title="Create an evaluation override">
    Use [POST /v2/evaluation\_overrides](/v2/reference/createevaluationoverride). At minimum you must provide a `customer_id` and a `reason`.

    **Example: Fraud override for a customer**

    After reviewing a fraud case, an agent determines the decline was a false positive and creates an override so the customer can transact normally for the next 24 hours:

    ```shell theme={"system"}
    curl \
      -X POST \
      -H "Authorization: Bearer $apikey" \
      -H 'Content-Type: application/json' \
      https://api.synctera.com/v2/evaluation_overrides \
      --data-binary '
      {
        "customer_id": "5f4ff599-7c29-4f69-a3d9-e103e151afbd",
        "type": "FRAUD",
        "reason": "False positive - customer confirmed transaction is legitimate.",
        "active_at": "2024-06-01T00:00:00.000Z",
        "expires_at": "2024-06-02T00:00:00.000Z"
      }'
    ```

    **Example: Spend-control override for a specific account and spend control**

    A customer needs to make a one-time purchase that exceeds their weekly card limit. The override is scoped to their specific account and spend control:

    ```shell theme={"system"}
    curl \
      -X POST \
      -H "Authorization: Bearer $apikey" \
      -H 'Content-Type: application/json' \
      https://api.synctera.com/v2/evaluation_overrides \
      --data-binary '
      {
        "customer_id": "5f4ff599-7c29-4f69-a3d9-e103e151afbd",
        "account_id": "30044785-ddb0-4a51-be1c-402bd4ba2b2b",
        "spend_control_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "type": "SPEND_CONTROL",
        "reason": "One-time exception for large appliance purchase.",
        "active_at": "2024-06-01T00:00:00.000Z",
        "expires_at": "2024-06-01T23:59:59.000Z"
      }'
    ```

    The response includes the system-generated `id`, `creation_time`, and `last_updated_time`:

    ```json theme={"system"}
    {
      "id": "74454076-c36b-44fb-8062-d1743d668236",
      "customer_id": "5f4ff599-7c29-4f69-a3d9-e103e151afbd",
      "account_id": "30044785-ddb0-4a51-be1c-402bd4ba2b2b",
      "spend_control_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "type": "SPEND_CONTROL",
      "reason": "One-time exception for large appliance purchase.",
      "active_at": "2024-06-01T00:00:00.000Z",
      "expires_at": "2024-06-01T23:59:59.000Z",
      "creation_time": "2024-05-31T14:22:08.123Z",
      "last_updated_time": "2024-05-31T14:22:08.123Z"
    }
    ```
  </Step>

  <Step title="List and review overrides">
    Use [GET /v2/evaluation\_overrides](/v2/reference/listevaluationoverrides) to list overrides. You can filter by customer, account, card, spend control, transaction, type, or reason.

    ```shell theme={"system"}
    curl \
      -X GET \
      -H "Authorization: Bearer $apikey" \
      "https://api.synctera.com/v2/evaluation_overrides?customer_id=5f4ff599-7c29-4f69-a3d9-e103e151afbd&type=FRAUD"
    ```

    To retrieve a single override by ID, use [GET /v2/evaluation\_overrides/\{evaluation\_override\_id}](/v2/reference/getevaluationoverride):

    ```shell theme={"system"}
    curl \
      -X GET \
      -H "Authorization: Bearer $apikey" \
      "https://api.synctera.com/v2/evaluation_overrides/74454076-c36b-44fb-8062-d1743d668236"
    ```
  </Step>

  <Step title="Update an override">
    Use [PATCH /v2/evaluation\_overrides/\{evaluation\_override\_id}](/v2/reference/updateevaluationoverride) to modify an existing override. You can update the `active_at`, `expires_at`, and `reason` fields.

    For example, to extend an override's expiration:

    ```shell theme={"system"}
    curl \
      -X PATCH \
      -H "Authorization: Bearer $apikey" \
      -H 'Content-Type: application/json' \
      https://api.synctera.com/v2/evaluation_overrides/74454076-c36b-44fb-8062-d1743d668236 \
      --data-binary '
      {
        "expires_at": "2024-06-07T23:59:59.000Z",
        "reason": "Extended override - customer traveling internationally this week."
      }'
    ```
  </Step>

  <Step title="Delete an override">
    To remove an override immediately (rather than waiting for it to expire), use [DELETE /v2/evaluation\_overrides/\{evaluation\_override\_id}](/v2/reference/deleteevaluationoverride):

    ```shell theme={"system"}
    curl \
      -X DELETE \
      -H "Authorization: Bearer $apikey" \
      "https://api.synctera.com/v2/evaluation_overrides/74454076-c36b-44fb-8062-d1743d668236"
    ```
  </Step>
</Steps>

## Best practices

<Warning>
  Evaluation overrides bypass safety controls. Use them judiciously and always with a clear, documented reason.
</Warning>

* **Set an expiration** — Always provide an `expires_at` value so overrides don't persist longer than intended. Prefer the shortest window that covers the customer's need.
* **Scope narrowly** — Use `account_id`, `card_id`, `spend_control_id`, or `transaction_id` to limit the override to only what's necessary rather than giving a blanket bypass for the customer.
* **Document the reason** — Write a clear, specific `reason` that a compliance reviewer can understand later (e.g., *"False positive — customer confirmed wire to known payee"* rather than *"override"*).
* **Review regularly** — Use the list endpoint with filters to audit active overrides and ensure none have been left in place longer than needed.
* **Prefer deletion over expiry for immediate revocation** — If circumstances change and the override is no longer appropriate, delete it rather than waiting for it to expire.

## API reference

See the full Evaluation Overrides API reference for request/response schemas and all available parameters:

* [List evaluation overrides](/v2/reference/listevaluationoverrides)
* [Create an evaluation override](/v2/reference/createevaluationoverride)
* [Get an evaluation override](/v2/reference/getevaluationoverride)
* [Update an evaluation override](/v2/reference/updateevaluationoverride)
* [Delete an evaluation override](/v2/reference/deleteevaluationoverride)