Fraud examples

Realistic request/response shapes for partner scoring and report handoff. Field lists follow stream + report contracts; trim to what your revision’s OpenAPI requires.

ML scoring — success

Request: see quickstart.

Response (illustrative):

{
  "account_holder": "user-001",
  "transaction_id": "5753ed0f-7c8e-4bdc-8056-d8dd50fc1db0",
  "check_type": "ml_check",
  "prediction": {
    "probability_score": 0.42,
    "predicted_level": "Mid Risk",
    "interpretation": {},
    "observations": {}
  },
  "timestamp": "2024-12-31 21:55:45"
}

predicted_level must stay consistent with report-compose score bands or compose rejects with ML_SCORE_TIER_CONFLICT — output contract.

Rule scoring — success

{
  "account_holder": "user-001",
  "transaction_id": "5753ed0f-7c8e-4bdc-8056-d8dd50fc1db0",
  "check_type": "rule_based_check",
  "prediction": {
    "flagged": true,
    "score": 0.8,
    "passed_conditions": [],
    "failed_conditions": [
      { "field": "transaction.amount", "operator": "GT", "value": 100000 }
    ]
  },
  "timestamp": "2024-12-31 21:55:45"
}

Note: in rule engine naming, failed_conditions holds predicates that matched.

Cold start

Omit lastCheckReport on ML payload (or send null). ML may apply limited rule/blacklist behaviour; for thin-history customers prefer rule scoring. No profile persistence is expected when history is insufficient.

Report callback (outbound to your backend)

POST /transaction/create-report HTTP/1.1
Authorization: ApiKey <ai-signed-jwt>
x-tenant-id: <tenant>
Content-Type: application/json

Illustrative body (provisional policy):

{
  "aiSummary": "Narrative text…",
  "fraudScore": 42,
  "riskCategory": "medium",
  "fraudIndicators": [],
  "indicatorRecords": [],
  "aiRecommendation": ["pend"],
  "decision": "pend",
  "escalations": [],
  "reasonCodes": ["CATEGORY_MEDIUM"],
  "aiChecks": [],
  "provenance": {
    "contractVersion": "fraud-output-v3",
    "policyVersion": "fraud-decision-v1",
    "predictionSource": "ml_check",
    "predictionHash": "…",
    "modelNarrativeVersion": "gemini-summary-v1",
    "sourceScore": 42,
    "checkTypeDeclared": "ml_check"
  }
}

Full callback contract: Fraud report callback.

Authentication failure

{ "detail": "Invalid authorization scheme" }

HTTP 401 — e.g. Bearer used instead of ApiKey.

Contract-validation failure (report compose)

When prediction identity keys are mixed or score/tier disagree, compose fails with stable codes such as:

Code	Meaning
AMBIGUOUS_PREDICTION_CONTRACT	ML and rule identity keys combined incorrectly
ML_SCORE_TIER_CONFLICT	predicted_level disagrees with score bands

Do not retry the same body. Fix the emitter — output contract.