---
title: "Feedback API"
description: "Investigation outcomes and feedback writes."
collection: "api-reference"
slug: "feedback"
url: "https://naiza.ai/docs/api-reference/feedback"
markdown: "https://naiza.ai/docs/api-reference/feedback.md"
full_docs: "https://naiza.ai/docs.md"
product: "Naiza"
base_url: "https://api.naiza.ai/api/v1"
---

# Feedback API

> Investigation outcomes and feedback writes.

## Table of contents

- [Auth](#auth)
- [Endpoints](#endpoints)
- [Label Decision](#label-decision)
  - [Endpoint](#endpoint)
  - [Headers](#headers)
  - [Request](#request)
  - [Response](#response)
- [Label Event](#label-event)
  - [Endpoint](#endpoint)
  - [Request](#request)
- [Feedback Labels](#feedback-labels)
- [Idempotency](#idempotency)
  - [Example with Idempotency](#example-with-idempotency)
- [Examples](#examples)
  - [cURL](#curl)
  - [Node.js](#nodejs)
  - [Python](#python)
- [Best Practices](#best-practices)
  - [1. Use Idempotency Keys](#1-use-idempotency-keys)
  - [2. Include External Case IDs](#2-include-external-case-ids)
  - [3. Provide Detailed Notes](#3-provide-detailed-notes)
  - [4. Handle Retries](#4-handle-retries)
- [Troubleshooting](#troubleshooting)

The Feedback API allows you to provide feedback on decisions and events to improve fraud detection accuracy.

## Auth

`x-api-key` is required.

## Endpoints

- `POST /api/v1/feedback/decision/:id`
- `POST /api/v1/feedback/event/:id`

## Label Decision

Provide feedback on a decision outcome.

### Endpoint

```http
POST /api/v1/feedback/decision/:id
```

### Headers

| Header | Description |
|--------|-------------|
| `Idempotency-Key` | Optional. Unique key to prevent duplicate submissions |

### Request

```json
{
  "label": "FRAUD",
  "notes": "Customer confirmed this was fraudulent activity",
  "externalCaseId": "case_12345"
}
```

### Response

```json
{
  "id": "feedback_abc123",
  "type": "DECISION",
  "targetId": "evt_ckm9876543210",
  "label": "FRAUD",
  "notes": "Customer confirmed this was fraudulent activity",
  "externalCaseId": "case_12345",
  "createdAt": "2025-01-15T10:00:00Z",
  "updatedAt": "2025-01-15T10:00:00Z"
}
```

## Label Event

Provide feedback on an event outcome.

### Endpoint

```http
POST /api/v1/feedback/event/:id
```

### Request

Same format as decision feedback.

## Feedback Labels

| Label | Description |
|-------|-------------|
| `FRAUD` | Confirmed fraudulent activity |
| `LEGIT` | Confirmed legitimate activity |
| `CHARGEBACK` | Chargeback occurred |
| `REFUND` | Refund was issued |
| `FALSE_POSITIVE` | Decision was incorrect (blocked legitimate transaction) |
| `TRUE_POSITIVE` | Decision was correct (blocked fraudulent transaction) |

## Idempotency

Feedback endpoints support idempotency to prevent duplicate submissions. Include `Idempotency-Key`:

```http
POST /api/v1/feedback/decision/evt_123
Idempotency-Key: unique-key-here
Content-Type: application/json

{
  "label": "FRAUD",
  "notes": "Customer confirmed fraud"
}
```

**Expected behavior:**
- First request: processed normally and the response is stored for replay
- Duplicate key (same tenant + same endpoint path): returns the stored response body
- Keys expire after 24 hours
- Reuse the same key for safe retries of the same logical action

### Example with Idempotency

```javascript
const idempotencyKey = `feedback-${decisionId}-${Date.now()}`;

const response = await fetch(
  `https://api.naiza.ai/api/v1/feedback/decision/${decisionId}`,
  {
    method: 'POST',
    headers: {
      'x-api-key': 'naiza_api_sk_live_...',
      'Idempotency-Key': idempotencyKey,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      label: 'FRAUD',
      notes: 'Customer confirmed fraud',
    }),
  }
);

// Safe to retry with same idempotency key
// Will return cached response if already processed
```

## Examples

### cURL

```bash
# Label decision as fraud
curl -X POST https://api.naiza.ai/api/v1/feedback/decision/evt_123 \
  -H "x-api-key: naiza_api_sk_live_..." \
  -H "Idempotency-Key: feedback-evt_123-1234567890" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "FRAUD",
    "notes": "Customer confirmed this was fraudulent",
    "externalCaseId": "case_12345"
  }'
```

### Node.js

```javascript
async function submitFeedback(decisionId, label, notes) {
  const idempotencyKey = `feedback-${decisionId}-${Date.now()}`;
  
  const response = await fetch(
    `https://api.naiza.ai/api/v1/feedback/decision/${decisionId}`,
    {
      method: 'POST',
      headers: {
        'x-api-key': process.env.NAIZA_API_KEY,
        'Idempotency-Key': idempotencyKey,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        label,
        notes,
        externalCaseId: `case_${Date.now()}`,
      }),
    }
  );
  
  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error.message);
  }
  
  return response.json();
}

// Usage
await submitFeedback('evt_123', 'FRAUD', 'Customer confirmed fraud');
```

### Python

```python
import requests
import time
import os

def submit_feedback(decision_id, label, notes):
    idempotency_key = f"feedback-{decision_id}-{int(time.time())}"
    
    response = requests.post(
        f'https://api.naiza.ai/api/v1/feedback/decision/{decision_id}',
        headers={
            'x-api-key': os.getenv('NAIZA_API_KEY'),
            'Idempotency-Key': idempotency_key,
            'Content-Type': 'application/json',
        },
        json={
            'label': label,
            'notes': notes,
            'externalCaseId': f'case_{int(time.time())}',
        },
    )
    
    response.raise_for_status()
    return response.json()

# Usage
submit_feedback('evt_123', 'FRAUD', 'Customer confirmed fraud')
```

## Best Practices

### 1. Use Idempotency Keys

Always use idempotency keys when submitting feedback to prevent duplicates:

```javascript
const idempotencyKey = `${decisionId}-${label}-${timestamp}`;
```

### 2. Include External Case IDs

Link feedback to your internal case management system:

```json
{
  "label": "FRAUD",
  "externalCaseId": "case_12345",
  "notes": "Linked to support ticket #12345"
}
```

### 3. Provide Detailed Notes

Include context in notes for better model training:

```json
{
  "label": "FALSE_POSITIVE",
  "notes": "Customer verified identity via phone call. Original decision was incorrect."
}
```

### 4. Handle Retries

Implement retry logic with the same idempotency key:

```javascript
async function submitFeedbackWithRetry(decisionId, label, notes, maxRetries = 3) {
  const idempotencyKey = `feedback-${decisionId}-${label}`;
  
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await submitFeedback(decisionId, label, notes, idempotencyKey);
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await sleep(Math.pow(2, i) * 1000); // Exponential backoff
    }
  }
}
```

## Troubleshooting

- `404`: target decision/event ID not found in your tenant scope
- `401`: missing/invalid API key
- `422`/`400`: body validation failed (invalid `label`, oversized `notes`, etc.)

## Related documentation

- [API Overview](https://naiza.ai/docs/api-reference/overview.md) — Base URL, versioning, and high-level API surface.
- [Authentication](https://naiza.ai/docs/api-reference/authentication.md) — API keys, Web SDK tokens, and secure key handling.
- [Web SDK API](https://naiza.ai/docs/api-reference/websdk.md) — Browser SDK endpoints and device signal collection.
- [Events API](https://naiza.ai/docs/api-reference/events.md) — Submit and query product events for risk evaluation.
- [Sessions API](https://naiza.ai/docs/api-reference/sessions.md) — Session grouping and timeline endpoints.
- [Error Handling](https://naiza.ai/docs/api-reference/errors.md) — Error shapes, status codes, and retry guidance.
- [Rate Limiting](https://naiza.ai/docs/api-reference/rate-limiting.md) — Quota headers and rate-limit behavior.
- [Decisions API](https://naiza.ai/docs/api-reference/decisions.md) — approve / deny / review evaluation and decision payloads (Events API uses ALLOW/REVIEW/BLOCK).

---

*Source: [https://naiza.ai/docs/api-reference/feedback](https://naiza.ai/docs/api-reference/feedback) · Full docs: [https://naiza.ai/docs.md](https://naiza.ai/docs.md)*