POST /v1/decisions — Submit or Override Fraud Decision

Use this endpoint to record the outcome of a manual review or to override a decision that FraudEG’s automated scoring engine returned. You would typically call it after an analyst finishes reviewing a flagged transaction, after a customer successfully completes identity verification that clears a challenge, or when applying a policy exception approved by your compliance team. Every call creates an immutable audit record that FraudEG associates with the original transaction.

Endpoint

POST https://api.fraudeg.com/v1/decisions

Request Headers

Header	Value	Required
`Authorization`	`Bearer <API_KEY>`	Yes
`Content-Type`	`application/json`	Yes

Request Body

string

required

The FraudEG transaction ID returned by POST /v1/transactions/score. This links the decision to the original risk assessment.

string

required

The decision to record for this transaction. Accepted values:

allow — Approve the transaction.
challenge — Route the transaction to step-up authentication.
block — Decline the transaction.

string

required

A structured reason code explaining why this decision was made. Accepted values:

manual_review — Decision follows a completed manual review.
customer_verified — Customer passed additional verification (e.g., OTP, ID check).
false_positive — The automated model flagged a legitimate transaction incorrectly.
confirmed_fraud — Analyst confirmed the transaction is fraudulent.
policy_exception — A pre-approved policy exception applies.

string

Free-text analyst notes attached to the audit record. Maximum 1,000 characters. Use this field to document evidence, customer communication references, or escalation context.

string

Your internal ID for the analyst or reviewer who made this decision. Stored in the audit record to support accountability reporting.

Response Fields

string

Unique FraudEG identifier for this decision record. Use this ID when referencing the decision in support tickets or compliance reports.

string

The transaction ID this decision is associated with, echoed back from your request.

string

The recorded decision (allow, challenge, or block), confirmed by the API.

string

The recorded reason code, confirmed by the API.

string

ISO 8601 timestamp of when the decision was recorded (e.g., "2024-11-15T11:05:00Z").

Code Examples

curl --request POST \
  --url https://api.fraudeg.com/v1/decisions \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "transaction_id": "txn_9kLmN3pQ7rS",
    "decision": "allow",
    "reason": "false_positive",
    "notes": "Customer called in and completed knowledge-based auth. Original block due to velocity flag on shared IP — confirmed legitimate corporate network.",
    "analyst_id": "analyst_77"
  }'

const response = await fetch('https://api.fraudeg.com/v1/decisions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    transaction_id: 'txn_9kLmN3pQ7rS',
    decision: 'allow',
    reason: 'false_positive',
    notes: 'Customer called in and completed knowledge-based auth. Original block due to velocity flag on shared IP — confirmed legitimate corporate network.',
    analyst_id: 'analyst_77',
  }),
});

const data = await response.json();
console.log(data);
// {
//   decision_id: 'dec_4nWvQ1mR8xZ',
//   transaction_id: 'txn_9kLmN3pQ7rS',
//   decision: 'allow',
//   reason: 'false_positive',
//   created_at: '2024-11-15T11:05:00Z'
// }

Example Response

{
  "decision_id": "dec_4nWvQ1mR8xZ",
  "transaction_id": "txn_9kLmN3pQ7rS",
  "decision": "allow",
  "reason": "false_positive",
  "created_at": "2024-11-15T11:05:00Z"
}

Decision records are immutable. Once you submit a decision via this endpoint, it cannot be edited or deleted — this is by design to maintain a trustworthy audit trail for compliance and dispute resolution. If you need to record a correction, submit a new decision for the same transaction_id; all decisions in the chain are preserved and timestamped.

Every decision you submit with reason: "false_positive" or reason: "confirmed_fraud" is used as a labeled training signal to continuously retrain FraudEG’s ML models for your account. The more decisions your team submits, the more accurately the scoring engine adapts to your specific user base and fraud patterns. Aim to label at least 80% of manually reviewed transactions for the best model performance.

Overview

Transactions

Identity

Monitoring

POST /v1/decisions — Submit or Override Fraud Decision

Endpoint

Request Headers

Request Body

Response Fields

Code Examples

Example Response

​Endpoint

​Request Headers

​Request Body

​Response Fields

​Code Examples

​Example Response

Endpoint

Request Headers

Request Body

Response Fields

Code Examples

Example Response