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

# POST /v1/feedback

> Submit corrections to improve detection accuracy

Every correction you submit helps the system learn. Corrections drive contradiction detection, rule formulation, and accuracy improvements specific to your data.

## Authentication

```
X-API-Key: am_live_your_key_here
```

## Batch Format (Preferred)

Submit multiple corrections in a single request. Each correction references either a placeholder from the sanitize response or raw text for missed entities.

| Field | Type | Required | Description |
| - | - | - | - |
| `session_id` | string | Yes | Session ID from the sanitize response |
| `corrections` | array | Yes | Array of correction objects (max 50) |
| `corrections[].placeholder` | string | Conditional | Reference to `[TYPE_N]` placeholder. Required for `misclassification` and `false_positive` |
| `corrections[].span_text` | string | Conditional | Raw text span. Required for `missed_entity` |
| `corrections[].correct_type` | string | Conditional | What the entity should be classified as. Required for `misclassification` and `missed_entity` |
| `corrections[].feedback_type` | string | Yes | `misclassification`, `false_positive`, `missed_entity`, or `wrong_type` |

### Example Request

```bash theme={null}
curl -X POST https://api.ambientmeta.com/v1/feedback \
  -H "X-API-Key: am_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "ses_a1b2c3d4e5f6",
    "corrections": [
      {"placeholder": "[PHONE_NUMBER_1]", "correct_type": "NPI", "feedback_type": "misclassification"},
      {"span_text": "Dr. Jane Smith", "correct_type": "PERSON", "feedback_type": "missed_entity"},
      {"placeholder": "[SSN_1]", "feedback_type": "false_positive"}
    ]
  }'
```

### Example Response

```json theme={null}
{
  "accepted": 3,
  "correction_ids": ["cor_xxx", "cor_yyy", "cor_zzz"],
  "contradictions_detected": 1,
  "message": "Thank you. 1 contradiction detected — check /v1/insights for details.",
  "status": "recorded"
}
```

## Response Fields

| Field | Type | Description |
| - | - | - |
| `accepted` | integer | Number of corrections accepted |
| `correction_ids` | array | IDs assigned to each correction |
| `contradictions_detected` | integer | Number of contradictions found against previous corrections |
| `message` | string | Human-readable summary |
| `status` | string | Always `"recorded"` |

<Info>
  **Contradiction detection is automatic.** When you correct an entity in one direction (e.g., PHONE\_NUMBER to NPI) and a previous correction went the other way (NPI to PHONE\_NUMBER), the system detects this as a contradiction and creates an insight. Check [GET /v1/insights](/api-reference/insights) for details and resolution options.
</Info>

## Feedback Types

| Type | When to Use | Required Fields |
| - | - | - |
| `misclassification` | Entity was detected but classified as the wrong type | `placeholder` + `correct_type` |
| `wrong_type` | Alias for `misclassification` | `placeholder` + `correct_type` |
| `missed_entity` | System failed to detect an entity | `span_text` + `correct_type` |
| `false_positive` | System flagged something that is not PII | `placeholder` |

## Legacy Single-Correction Format

The original single-correction format is still supported for backwards compatibility.

| Field | Type | Required | Description |
| - | - | - | - |
| `session_id` | string | Yes | Session ID from the sanitize response |
| `feedback_type` | string | Yes | `wrong_type`, `missed_entity`, `false_positive`, or `misclassification` |
| `text_snippet` | string | Yes | The text span being corrected |
| `expected_type` | string | No | What the entity should be classified as |

### Legacy Example

```bash theme={null}
curl -X POST https://api.ambientmeta.com/v1/feedback \
  -H "X-API-Key: am_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "ses_a1b2c3d4e5f6",
    "feedback_type": "wrong_type",
    "text_snippet": "1234567890",
    "expected_type": "NPI"
  }'
```

## SDK Example

```python theme={null}
from ambientmeta import AmbientMeta

client = AmbientMeta(api_key="am_live_xxx")

# Sanitize first
result = client.sanitize("Contact NPI 1234567890 at 555-867-5309")

# Chain corrections on the result
result.correct("[PHONE_NUMBER_1]", "NPI")         # Misclassified
result.report_missed("Dr. Smith", "PERSON")       # Missed entity
result.report_false_positive("[LOCATION_1]")       # False positive

# Submit all corrections at once
feedback = result.submit_corrections()
print(f"Accepted: {feedback.accepted}, Contradictions: {feedback.contradictions_detected}")
```

## Errors

| Code | HTTP Status | Description |
| - | - | - |
| `invalid_api_key` | 401 | API key is missing or invalid |
| `session_not_found` | 404 | Session ID doesn't exist or has expired |
| `rate_limited` | 429 | Too many requests |

[View all error codes](/api-reference/errors)


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