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

# Submit feedback

> POST /feedback — confirmed fraud or legitimate labels

**Request**

```http theme={null}
POST {BASE_URL}/api/v1/feedback
X-API-Key: <your-api-key>
Content-Type: application/json

{
  "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
  "is_fraud": true,
  "fraud_type": "ATO",
  "confirmed_by": "analyst_001",
  "notes": "Confirmed account takeover via device fingerprint mismatch"
}
```

**Response**

```http theme={null}
HTTP/1.1 201 Created
Content-Type: application/json

{
  "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
  "is_fraud": true,
  "fraud_type": "ATO",
  "confirmed_by": "analyst_001",
  "confirmed_at": "2025-06-15T16:00:00Z"
}
```

Submits a confirmed label (fraud or legitimate) for a transaction previously scored with `POST /score` or `POST /score/batch`. Closes the feedback loop for monitoring and model improvement.

**Authentication:** `X-API-Key`.

## Request body

| Field | Type | Description |
| - | - | - |
| `transaction_id` | UUID | UUID of the scored transaction |
| `is_fraud` | boolean | `true` = confirmed fraud; `false` = legitimate |
| `fraud_type` | string | Required when `is_fraud=true`. See [fraud\_type](/docs/shield/reference/enums#fraud_type-feedback) |
| `confirmed_by` | string | Analyst or system ID (1–64 characters) |

### Optional fields

| Field | Type | When to send |
| - | - | - |
| `notes` | string | Investigation context (max 2,000 characters) |

> [!NOTE]
>
> When `is_fraud=false`, **do not include** `fraud_type`. The transaction must already exist in Kairo Shield (it must have been scored).

## Response fields

| Field | Description |
| - | - |
| `transaction_id` | UUID of the labeled transaction |
| `is_fraud` | Confirmed label |
| `fraud_type` | Fraud type (only when `is_fraud=true`) |
| `confirmed_by` | Who recorded the label |
| `confirmed_at` | UTC timestamp when the label was persisted |

If you subscribe to `feedback.received` webhooks, you will receive a POST for this event.

## More request examples

**Confirmed fraud — ATO**

```json theme={null}
{
  "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
  "is_fraud": true,
  "fraud_type": "ATO",
  "confirmed_by": "analyst_001",
  "notes": "Confirmed account takeover via device fingerprint mismatch"
}
```

**Legitimate transaction**

```json theme={null}
{
  "transaction_id": "660e8400-e29b-41d4-a716-446655440001",
  "is_fraud": false,
  "confirmed_by": "analyst_002",
  "notes": "Manual review: typical user behavior"
}
```

**Confirmed fraud — friendly fraud**

```json theme={null}
{
  "transaction_id": "770e8400-e29b-41d4-a716-446655440002",
  "is_fraud": true,
  "fraud_type": "FRIENDLY_FRAUD",
  "confirmed_by": "chargeback_team",
  "notes": "Unfounded chargeback after confirmed delivery"
}
```

## Typical errors

* **401** — Invalid API Key
* **404** — Transaction not found for your client
* **422** — Missing `fraud_type` when `is_fraud=true`, or invalid enum

## See also

* [Real-time scoring](/docs/shield/api/score)
* [fraud\_type](/docs/shield/reference/enums#fraud_type-feedback)
* [Webhook events](/docs/shield/webhooks/events)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.