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

# POST /v1/decisions — Submit or Override Fraud Decision

> POST /v1/decisions — manually submit or override a FraudEG fraud decision for a transaction, with a reason and analyst notes for audit trail.

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

```http theme={null}
POST https://api.fraudeg.com/v1/decisions
```

## Request Headers

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

## Request Body

<ParamField body="transaction_id" type="string" required>
  The FraudEG transaction ID returned by `POST /v1/transactions/score`. This links the decision to the original risk assessment.
</ParamField>

<ParamField body="decision" type="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.
</ParamField>

<ParamField body="reason" type="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.
</ParamField>

<ParamField body="notes" type="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.
</ParamField>

<ParamField body="analyst_id" type="string">
  Your internal ID for the analyst or reviewer who made this decision. Stored in the audit record to support accountability reporting.
</ParamField>

## Response Fields

<ResponseField name="decision_id" type="string">
  Unique FraudEG identifier for this decision record. Use this ID when referencing the decision in support tickets or compliance reports.
</ResponseField>

<ResponseField name="transaction_id" type="string">
  The transaction ID this decision is associated with, echoed back from your request.
</ResponseField>

<ResponseField name="decision" type="string">
  The recorded decision (`allow`, `challenge`, or `block`), confirmed by the API.
</ResponseField>

<ResponseField name="reason" type="string">
  The recorded reason code, confirmed by the API.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of when the decision was recorded (e.g., `"2024-11-15T11:05:00Z"`).
</ResponseField>

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript Node.js theme={null}
  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'
  // }
  ```
</CodeGroup>

### Example Response

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

<Note>
  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.
</Note>

<Tip>
  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.
</Tip>