# Fraud Detection API — LLM Integration Guide Version: 1.0.0 Base URL: https://fraud-detection-api.up.railway.app/api/v1 Auth: Bearer token in Authorization header (obtained from RapidAPI) OpenAPI spec: https://fraud-detection-api.up.railway.app/api/v1/openapi.json ## What this API does Scores financial transactions for fraud risk in real time. Returns a fraud_probability (0–1), risk_level (LOW/MEDIUM/HIGH/CRITICAL), and an array of human-readable reasons explaining the score. Automatically learns each user's behaviour over time. ## Authentication All endpoints except /health require: Authorization: Bearer ## Endpoints ### POST /analyze-transaction Required body fields (all strings unless noted): user_id - your internal user ID amount - number, must be > 0 currency - ISO 4217 code e.g. "USD" location - city/region string device - device name or fingerprint ip_address - IPv4 or IPv6 timestamp - ISO 8601 datetime merchant - merchant name transaction_type - one of: online | in_store | atm | wire_transfer | p2p Success response (200): transaction_id - string (MongoDB ObjectId) fraud_probability - float 0–1 risk_level - "LOW" | "MEDIUM" | "HIGH" | "CRITICAL" reasons - string[] of signals that fired blocked - boolean (true when CRITICAL) analyzed_at - ISO 8601 datetime score_breakdown - object with per-signal scores (Pro plan only) ### GET /transactions/:user_id?page=1&limit=10 Returns paginated transaction history for a user. Basic plan: max 10 per page. Pro plan: max 100 per page. ### GET /users/:user_id/risk-profile Returns the learned behavioural profile: avg_transaction_amount, max_transaction_amount, total_transactions, known_devices_count, known_locations_count, is_blocked, high_risk_transactions_30d Pro plan also returns: known_devices[], known_locations[] ### GET /dashboard/stats Returns: overview (total, 24h, high_risk_24h, blocked_users), risk_distribution_7d (LOW/MEDIUM/HIGH/CRITICAL counts). Pro plan also returns risk_trend_30d (day-by-day array). ### GET /health No auth required. Returns: status, uptime, database, timestamp. ## Risk levels LOW fraud_probability < 0.35 — approve MEDIUM 0.35 – 0.59 — flag for review / add friction HIGH 0.60 – 0.79 — webhook alert fired CRITICAL >= 0.80 — transaction blocked, user flagged, webhook fired ## Scoring signals (weight) amount_anomaly 25% — ratio of amount to user's avg spend new_device 15% — device not in user's history location_anomaly 15% — location not in user's history high_frequency 15% — transactions in last 10 minutes new_ip 10% — IP not in user's history night_activity 10% — 1–5 AM UTC high_amount 5% — absolute thresholds ($5k/$10k/$20k+) transaction_type_risk 5% — wire_transfer > p2p > online > atm > in_store ## Rate limits Basic plan: 50 requests/minute Pro plan: 500 requests/minute Exceeded: HTTP 429 ## Common errors 400 — missing/invalid fields (see missing_fields array in response) 401 — missing or invalid API key 403 — user is blocked (prior CRITICAL transaction) 404 — user not found (no transactions analyzed yet for this user_id) 429 — rate limit exceeded 500 — internal server error ## Integration example (JavaScript fetch) const response = await fetch( 'https://fraud-detection-api.up.railway.app/api/v1/analyze-transaction', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer YOUR_API_KEY' }, body: JSON.stringify({ user_id: 'user_123', amount: 250, currency: 'USD', location: 'New York', device: 'iPhone 15', ip_address: '192.168.1.1', timestamp: new Date().toISOString(), merchant: 'Amazon', transaction_type: 'online' }) } ); const { fraud_probability, risk_level, reasons, blocked } = await response.json(); if (blocked) { /* deny transaction */ } if (risk_level === 'HIGH') { /* trigger review flow */ } ## Integration example (Python requests) import requests resp = requests.post( 'https://fraud-detection-api.up.railway.app/api/v1/analyze-transaction', headers={'Authorization': 'Bearer YOUR_API_KEY'}, json={ 'user_id': 'user_123', 'amount': 250, 'currency': 'USD', 'location': 'New York', 'device': 'iPhone 15', 'ip_address': '192.168.1.1', 'timestamp': '2026-01-20T14:30:00Z', 'merchant': 'Amazon', 'transaction_type': 'online' } ) data = resp.json() print(data['risk_level'], data['fraud_probability']) ## Pro-only endpoints ### POST /batch/analyze Analyze multiple transactions at once. Body: { "transactions": [ ...array of transaction objects... ] } Basic plan: max 5 per batch. Pro plan: max 50 per batch. Response: { summary: { total, low, medium, high, critical, blocked, errors }, results: [...] } ### GET /network/device/:fingerprint How many unique user accounts used this device. Returns counts only plus risk_distribution and network_risk_score. Use to detect fraud rings sharing a single device across multiple accounts. ### GET /network/ip/:address Same as device lookup but by IP address. ### GET /network/location/:location Same as device lookup but by location string. ### GET /network/user/:user_id Full network graph — all devices/IPs/locations this user has used and how many other users share each. Returns: { network_risk: "NORMAL"|"ELEVATED", connections: { devices, ips, locations }, summary } ### POST /webhooks Register a URL for real-time fraud alerts. Body: { "url": "https://...", "events": ["HIGH", "CRITICAL"] } Response includes a "secret" for HMAC-SHA256 verification (store it, shown once). Verify incoming webhooks: check X-Fraud-Signature header = HMAC-SHA256(secret, requestBody). ### GET /webhooks List registered webhooks (secret not returned). ### DELETE /webhooks/:id Remove a webhook. ### PATCH /webhooks/:id/toggle Toggle is_active on/off. ### POST /rules Create a custom rule applied to every transaction for your API key. Body: { "name": string, "condition": string, "action": "block"|"escalate", "escalate_by": 0.3, "priority": 0 } Condition syntax: amount > 10000 transaction_type == "wire_transfer" location NOT IN known_locations device NOT IN known_devices transaction_type IN ["wire_transfer", "p2p"] fraud_probability > 0.5 amount > 5000 AND location NOT IN known_locations amount > 1000 OR transaction_type == "wire_transfer" Actions: block — forces risk_level=CRITICAL, blocked=true escalate — adds escalate_by to fraud_probability (default 0.3), re-classifies risk ### GET /rules List all rules sorted by priority (descending). ### PATCH /rules/:id Update a rule. Accepts: name, condition, action, escalate_by, priority, is_active. ### DELETE /rules/:id Delete a rule. ### POST /rules/test Test a condition without saving. Body: { "condition": string, "transaction": {...}, "user_profile": {...} } Returns: { matched: boolean } ### POST /users/:user_id/recalibrate Rebuild user profile from only clean (LOW/MEDIUM) transactions. Excludes fraud-flagged ones. Query param: include_medium=false to use only LOW transactions. Also unblocks the user if they were blocked. Returns: { recalibrated, clean_transactions_used, previous_profile, new_profile, unblocked } ## Notes for AI code generation - user_id is YOUR system's identifier — use your own user IDs, not UUIDs unless that's your scheme - The API learns user behaviour automatically — no setup needed per user - A user profile is created on their FIRST transaction analysis - amount must be a JSON number (not a string) - timestamp must be ISO 8601 format with timezone (Z or +offset) - transaction_type must exactly match one of the five enum values - blocked=true means you should deny the transaction in your application logic - The API does not process payments — it only scores risk - Custom rules are applied AFTER the base ML score, so they can only increase risk, not decrease it - Webhook secret is only shown once at registration — store it immediately - Recalibrate should be called after manually reviewing and clearing a user flagged by a false positive