Submit feedback

Request
Response

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"
}

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

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
Legitimate transaction
Confirmed fraud — friendly fraud

{
  "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"
}

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

{
  "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

Kairo Connect

Kairo Shield — Introduction

Kairo Shield — Getting started

Kairo Shield — API

Kairo Shield — Reference

Kairo Shield — Webhooks

Kairo Shield — Summary

Request body

Optional fields

Response fields

More request examples

Typical errors

See also

​Request body

​Optional fields

​Response fields

​More request examples

​Typical errors

​See also

Request body

Optional fields

Response fields

More request examples

Typical errors

See also