API Reference
/api/v1/feedback
Submit ground-truth feedback to continuously improve fraud detection accuracy.
The feedback endpoint accepts ground-truth labels for previous decisions. This data feeds into the model retraining pipeline and weight calibration system, continuously improving detection accuracy.
This endpoint requires a secret key (sk_). Feedback must be submitted server-side only — never expose sk_ keys in client code.
Request
POST /api/v1/feedbackbash
curl -X POST https://verifystack.io/api/v1/feedback \
-H "X-API-Key: sk_live_xxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"decisionId": "dec_abc123",
"actualOutcome": "chargeback",
"confidence": 1.0,
"notes": "Chargeback received from payment processor, amount $299.99"
}'Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| decisionId | string | One of three† | The decision ID from the persisted decision record |
| evidenceId | string | One of three† | The evidenceId from the original /decide response |
| userId | string | One of three† | The end-user ID from the original /decide request |
| actualOutcome | string | Yes | "fraud", "legitimate", "chargeback", "abuse", or "valid" |
| confidence | number | No | Confidence in the label (0.0–1.0, default 1.0) |
| notes | string | No | Free-text notes about the feedback (max 1000 chars) |
† At least one of decisionId, evidenceId, or userId is required to identify the original decision.
Rate Limits
Feedback has cumulative rate limits to prevent gaming:
| Limit | Value |
|---|---|
| Per hour | 50 submissions |
| Per day | 200 submissions |
| Max weight shift per feedback | 5% |
| Weight bounds | 2% – 40% |
How Feedback Works
- You submit an actualOutcome label for a previous decisionId, evidenceId, or userId
- The system verifies the original decision exists and checks evidence integrity
- Scoring weights are adjusted using optimistic locking with retry (max 3 attempts)
- The fraud graph is updated with the new label
- If consortium sharing is enabled, anonymized data is reported to the shared threat intelligence network