Implementation Guide

Feedback Intelligence

Build an outcome feedback loop: capture transaction IDs at scoring time, write feedback events, and monitor model quality with metrics.

Transaction scoring (API Reference)

Core sequence

Feedback is only useful when it maps back to a specific scored transaction. Follow this order to keep the feedback loop intact:

1Score the transaction via POST /v1/transactions/score and persist the returned transactionId.
2When an outcome is known, write feedback using POST /v1/feedback with a stable idempotency key.
3For high-volume pipelines, use POST /v1/feedback/batch (up to 100 items per request).
4Monitor model quality and detect score drift with GET /v1/feedback/metrics.

Warning

Never write feedback without a persisted transactionId from the score response. Feedback submitted with an unknown ID is rejected with a 404.

Base URL & auth

Base URL: https://api.maiguard.com

Write endpoints

Authorization: Bearer pk_live_<key>

Read endpoints

Authorization: Bearer pk_live_<key> or <jwt>

Note

Use pk_test_ during development. The test environment accepts feedback writes but excludes them from production metrics.

Endpoint matrix

Method	Endpoint	Auth	Purpose
POST	`/v1/transactions/score`	API key	Score a transaction and obtain a durable transactionId.
POST	`/v1/feedback`	API key	Submit a single feedback event for a scored transaction.
POST	`/v1/feedback/batch`	API key	Bulk-ingest up to 100 feedback events per request.
GET	`/v1/feedback/metrics`	API key / JWT	Query quality and drift metrics for a time window.

Examples

Persist the transactionId from the score response — you'll need it for every feedback write.

score-response.json

{
  "success": true,
  "data": {
    "transactionId": "8f0805f7-f203-4ce3-bf6f-272855f1e91b",
    "riskScore": 71,
    "decision": "REVIEW"
  }
}

Field reference

Valid enum values for the feedback write endpoints.

feedbackType

Determines the feedback category and which companion fields are required.

Value	Description	Required companion field
`TENANT_ACTION`	An operational decision made by your system or an agent (approve, decline, manual review).	`tenantAction`
`ANALYST_LABEL`	A ground-truth label assigned by a fraud analyst after investigation.	`analystLabel + confidence`

tenantAction

Required when feedbackType is TENANT_ACTION.

APPROVE

Transaction was approved and processed.

DECLINE

Transaction was declined by your system.

MANUAL_REVIEW

Flagged for human review — outcome pending.

CHARGEBACK

A chargeback was filed — strong fraud signal.

REFUND

Refund was issued (may indicate friendly fraud).

CANCELLED

Customer or system cancelled before settlement.

analystLabel + confidence

Required when feedbackType is ANALYST_LABEL.

analystLabel	Description
`TRUE_FRAUD`	Confirmed fraudulent transaction.
`FALSE_POSITIVE`	Legitimate transaction incorrectly flagged as risky.
`SUSPICIOUS`	Unusual pattern — not confirmed fraud, but warrants monitoring.
`LEGITIMATE`	Confirmed legitimate transaction.

confidence

CONFIRMED

High certainty — reviewed by a senior analyst or supported by external evidence.

confidence

PROBABLE

Likely outcome — analyst's best judgment without full confirmation.

confidence

POSSIBLE

Preliminary assessment — low certainty, useful as a soft training signal.

Metrics reference

Explanation of every field in the GET /v1/feedback/metrics response.

Field	Type	Description
`transactions.total`	number	Total transactions scored in the window.
`transactions.approvalRate`	float	Fraction of transactions that received ALLOW. Values near 1.0 may indicate rules are too permissive.
`feedback.eventsSubmitted`	number	Total feedback events written in the window.
`feedback.overrideRate`	float	Fraction of scored transactions where the tenant subsequently submitted an action that differed from the model's decision (e.g., model said BLOCK, tenant approved). A rising override rate can signal model drift or miscalibrated rules.
`labels.fraud`	number	Count of TRUE_FRAUD analyst labels in the window.
`labels.falsePositiveRate`	float	FALSE_POSITIVE labels ÷ total analyst labels. Target < 5% for healthy precision.
`adaptiveThreshold.recommendedThreshold`	number	MaiGuard-computed risk score threshold for the REVIEW boundary, based on your override and fraud label history. Use this to tune rule thresholds during phased rollouts.

Tip

Poll GET /v1/feedback/metrics weekly and compare overrideRate and adaptiveThreshold.recommendedThreshold against your current rule thresholds. A sustained override rate above 3% or a recommended threshold that differs from your live threshold by more than 10 points is a signal to re-tune.

Failure handling

All error responses use the same envelope:

error-response.json

{
  "error": "Conflict",
  "message": "Duplicate feedback idempotency key"
}

200 / 202Success or async accepted

400Validation error — check details array

404Unknown transactionId — ensure you persisted it at score time

409Duplicate idempotency key with different payload

429Rate limited — honor Retry-After header

500Transient — retry with exponential backoff

Idempotency

The Idempotency-Key header prevents duplicate feedback events on retry. Keys must be unique per logical outcome, not per HTTP attempt.

DOReuse the same key when retrying an identical feedback write.

DOUse a new key if the outcome itself changes (e.g., APPROVE → DECLINE).

DON'TNever reuse a key across different transactions.

DOKeep occurredAt as the real outcome time — not the retry timestamp.

Tip

A good idempotency key pattern: feedback-{orderId}-{action}-v1. The -v1 suffix lets you introduce a new logical outcome without reusing a stale key.

Rate limits

Single write

Per-tenant limit applied per endpoint — see API reference.

Batch write

Up to 100 items per request; total item count counts toward rate limit.

429 handling

Honor Retry-After and RateLimit-* response headers.

Metrics reads

Lower rate limit; intended for dashboard polling, not hot paths.

Full rate limits & feedback endpoint docs

Customer Onboarding

Fraud & AML (Operators)

Was this page helpful?