> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-en/rest-api/midapi-v2/document-services/document-validation/confirmacion-de-fraude.md).

# Fraud Confirmation

Yes, after a later review, it is confirmed that a specific transaction corresponded to an attempted fraud, the consumer can report it to the service. This information strengthens future detections on the same document or identity. This step is optional.

### Endpoint

```
POST /document/validate/fraud-report
```

### Headers

| Name              | Type   | Required | Description                                                                                                             |
| ----------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------- |
| **Authorization** | string | **Yes**  | consumer Token in format `Bearer <token>` (see [Authentication](/docs.facephi-en/rest-api/midapi-v2/autenticacion.md)). |
| **consumer-id**   | string | **Yes**  | consumer identifier.                                                                                                    |

### Request body

**Content-Type:** `application/json`

#### Parameters

| Parameter       | Type   | Required | Description                                                                                                 |
| --------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------- |
| `transactionId` | string | **Yes**  | UUID identifier of the validation transaction confirmed as fraud, as returned by `POST /document/validate`. |
| `categories`    | array  | **Yes**  | One or more categories of the detected fraud. Each value must be one of the **allowed values** (see below). |
| `comment`       | string | No       | Free-form comment, max. 500 characters.                                                                     |

#### Valid categories

The field `categories` only accepts the following values:

| Value                      | Description                                      |
| -------------------------- | ------------------------------------------------ |
| `DOCUMENT_MANIPULATED`     | The document is manipulated.                     |
| `DOCUMENT_ON_SCREEN`       | The document is shown from a screen.             |
| `DOCUMENT_PRINTED_COPY`    | The document is a printed copy.                  |
| `SELFIE_ON_SCREEN`         | The selfie is shown from a screen.               |
| `SELFIE_MANIPULATED`       | The selfie is manipulated.                       |
| `SELFIE_DOCUMENT_MISMATCH` | The selfie does not match the document portrait. |
| `INJECTED_MEDIA`           | The content (image/video) was injected.          |

{% hint style="info" %}
The field `categories` it accepts exactly the values in this table. Any other value is rejected with `400` and no action is logged.
{% endhint %}

#### Request example

```json
{
  "transactionId": "1c7d...e9",
  "categories": ["DOCUMENT_MANIPULATED", "SELFIE_MANIPULATED"],
  "comment": "Confirmed as fraud after internal review"
}
```

### Responses

#### `200` Success

```json
{
  "accepted": true
}
```

All applicable actions of the confirmation were logged correctly. This includes enrolling the face in the applicable blocklists (see below). The operation is **idempotent**: if the face was already in a blocklist, or if the transaction had already been reported previously, the retry is still considered a success and returns `200`.

#### `400` Bad Request

The request is invalid: missing `transactionId` or is not a UUID, `categories` is empty or contains an unsupported value (see **Valid categories**), or `comment` exceeds 500 characters. No action is logged; fix the request and try again.

#### `401` Unauthorized

Token missing, invalid, or expired.

#### `403` Forbidden

The consumer is not provisioned with the service `DOCUMENT_ANTIFRAUD`, or the consumer or its platform are inactive, expired, or out of service.

#### `404` Not Found

The indicated transaction does not exist or belongs to another consumer.

#### `422` Unprocessable Entity

The transaction does not support reporting: only completed transactions in state `COMPLETED`.

#### `429` Too Many Requests

The consumer has exceeded its request rate limit. The response includes `Retry-After` with the wait seconds, and `X-RateLimit-Limit` and `X-RateLimit-Burst` with the current thresholds. No action is logged.

#### `503` Service Unavailable

One of the applicable actions of the confirmation **could not be completed**. The confirmation is not considered fully logged; the consumer must **retry** later. The operation is idempotent, so retrying is safe.

Not all causes are solved by retrying: some require Facephi intervention. If the retry keeps returning `503`, **notify support** indicating the `transactionId`.

The body of an error response has the form described in [MIDAPI v2](/docs.facephi-en/rest-api/midapi-v2.md#respuestas-de-error).

### Face blocklists

When the transaction confirmed as fraud includes a selfie, its face is enrolled in the applicable blocklists so that future validations detect it (codes `200`/`201`, see [result response](/docs.facephi-en/rest-api/midapi-v2/document-services/document-validation/respuesta-de-resultado.md)):

* **Platform blocklist:** the face is always enrolled in the platform's own blocklist.
* **Global blocklist:** additionally, if the platform participates in the shared global blocklist, the face is enrolled there as well.

{% hint style="info" %}
Participation in the **global blocklist** is agreed with Facephi during service onboarding and is not controlled through the API. **By default the platform participates**; if you do not want to participate, indicate it during onboarding. Its scope is symmetrical: it applies both to the **search** during validation and to the **enrollment** in this fraud confirmation. If the transaction was processed without a selfie (without `TOKEN_FACE_IMAGE`), no face is enrolled in any blocklist.
{% endhint %}

{% hint style="info" %}
It is recommended to send a single fraud report per transaction. However, retrying is **safe**: the operation is idempotent and an already registered report returns `200` without duplicating effects.
{% endhint %}