Fraud Detection

Biometry includes an automated fraud detection engine that analyzes every biometric authentication transaction in real-time. When suspicious patterns are detected, the system flags the transaction and creates a fraud event with detailed evidence.

How it works

When a transaction is saved (e.g., after a process-video call), the fraud engine runs asynchronously and checks against 6 detection rules. If any rule triggers, the transaction is flagged and a fraud event is created with structured evidence.

This happens transparently — no changes needed in your integration. You can query fraud events via the API or CLI, and review them in the Biometry Console.

Detection Rules

Rule	What it detects	Severity	Flag
Impossible Travel	Same user authenticates from two locations that are physically impossible to travel between in the elapsed time (speed > 900 km/h)	High	`fraudulent`
Device Switching	Same user authenticates from a different device within a 5-minute window	Medium	`possibly_fraudulent`
Emulator Detection	Authentication attempt from a non-physical device (emulator/simulator)	High	`fraudulent`
IP Geo Anomaly	Country changes within the same session (e.g., starts in Australia, then request from Nigeria)	Medium	`possibly_fraudulent`
Rapid Fire	More than 5 `process-video` calls from the same user within 2 minutes	Medium	`possibly_fraudulent`
New Device + New Location	User authenticates from both a never-before-seen device AND a never-before-seen country simultaneously	High	`possibly_fraudulent`

All thresholds are configurable per deployment.

Fraud Flags

Every transaction has a flag field:

Flag	Meaning
`ok`	No fraud detected / explicitly cleared
`""` (empty, legacy/internal default if applicable)	No fraud detected
`possibly_fraudulent`	Suspicious activity detected, requires review
`fraudulent`	High-confidence fraud detected

Fraud Events API

Fraud events are queryable via dedicated API endpoints. All endpoints require user JWT authentication with fraud_analyst, admin, or owner project role.

List fraud events

curl -X POST 'https://api.biometrysolutions.com/api-transactions/fraud/events' \
  -H 'Authorization: Bearer <user-jwt>' \
  -H 'Content-Type: application/json' \
  -d '{
    "project_id": "your-project-id",
    "rule_name": "impossible_travel",
    "severity": "high",
    "page": 1,
    "page_size": 20
  }'

Available filters: project_id, rule_name, severity, user_fullname, from_date, to_date, page, page_size, sort_by, sort_order.

Get fraud event detail

curl 'https://api.biometrysolutions.com/api-transactions/fraud/events/<event-id>' \
  -H 'Authorization: Bearer <user-jwt>'

Returns the fraud event with its linked transaction details (device, geo, timestamps).

Get user risk profile

curl -X POST 'https://api.biometrysolutions.com/api-transactions/fraud/users/risk-profile' \
  -H 'Authorization: Bearer <user-jwt>' \
  -H 'Content-Type: application/json' \
  -d '{
    "project_id": "your-project-id",
    "user_fullname": "[email protected]"
  }'

Returns aggregated risk info: total events, events by rule/severity, known locations, known devices, and recent events.

Review a fraud event

curl -X PUT 'https://api.biometrysolutions.com/api-transactions/fraud/events/<event-id>/review?action=confirm_fraud' \
  -H 'Authorization: Bearer <user-jwt>'

The action query parameter accepts one of three values. Each sets a specific flag on the linked transaction:

Action	Transaction flag set	When to use
`confirm_fraud` (`ReviewActionConfirm`)	`"fraudulent"` (`FlagFraudulent`)	Analyst is certain the transaction is fraudulent — highest severity.
`dismiss` (`ReviewActionDismiss`)	`""` (`FlagOk`)	Transaction is legitimate; clears any pending flag.
`escalate` (`ReviewActionEscalate`)	`"possibly_fraudulent"` (`FlagPossiblyFraudulent`)	Analyst suspects fraud but needs further investigation — marks the transaction for follow-up without a definitive ruling.

Flag precedence: fraudulent > possibly_fraudulent > "".

Get fraud statistics

curl -X POST 'https://api.biometrysolutions.com/api-transactions/fraud/stats' \
  -H 'Authorization: Bearer <user-jwt>' \
  -H 'Content-Type: application/json' \
  -d '{
    "project_id": "your-project-id",
    "from_date": "<YYYY-MM-DD>",
    "to_date": "<YYYY-MM-DD>"
  }'

Returns: total count, counts by rule, counts by severity, top flagged users.

Manual Flagging

You can also manually flag transactions via the API:

curl -X PUT 'https://api.biometrysolutions.com/api-transactions/transactions/<transaction-id>/flag?flag=fraudulent' \
  -H 'Authorization: Bearer <api-key>'

Possible flags: fraudulent, possibly_fraudulent, ok (and "" only if your deployment still returns legacy empty values).

CLI Access

All fraud operations are available via the Biometry CLI:

biometry-cli fraud list --project-id <id>
biometry-cli fraud get <event-id>
biometry-cli fraud profile --project-id <id> --user [email protected]
biometry-cli fraud review <event-id> --action dismiss
biometry-cli fraud stats --project-id <id>

See the CLI documentation for installation and full command reference.

AI Agent Integration

The CLI is designed to be used by AI agents (like Claude Code) as a tool for autonomous fraud investigation. An agent can:

Pull unreviewed fraud events and triage them
Cross-reference user patterns across transactions
Bulk review obvious false positives (e.g., emulator detections from known test devices)
Generate natural-language summaries of fraud activity
Investigate complex fraud chains across sessions

This is the recommended approach for “agentic” fraud analysis — the intelligence lives in the agent, not in the backend.