Prembly
GuidesAPI Reference
Fraud LensFraud ScanScan an ID for fraud POST
POST
/api/v1/fraud/id-scan/

ID-Based Fraud Detection

Search the fraud bank by ID numbers (BVN, NIN, Passport, Driver's License, Voter's Card, etc.)

Features

  • Multiple ID Types: BVN, NIN, Passport, Driver's License, Voter's Card
  • Search Modes: Exact match or partial match
  • Optional Face Verification: Include face image for combined ID + face matching
  • Backward Compatible: Image field is optional - works with or without face image
  • Filters: Date range, fraud category, verified reports only
  • Risk Assessment: Automatic risk scoring (LOW/MEDIUM/HIGH/CRITICAL)
  • Recommendations: Context-aware fraud prevention recommendations

Use Cases

  • Customer onboarding verification
  • Transaction monitoring
  • Account recovery verification
  • Fraud investigation
  • KYC compliance checks
  • Combined ID + face verification for higher confidence

Risk Levels

  • LOW (0-29): No or minimal fraud history
  • MEDIUM (30-59): Some concerns, additional verification recommended
  • HIGH (60-79): Significant risk, manual review required
  • CRITICAL (80-100): Block transaction, report to authorities

Authentication: Requires X-API-Key header. Used by external integrations and API clients.

Authorization

ApiKeyAuth
X-API-Key<token>

In: header

Request Body

TypeScript Definitions

Use the request body type in TypeScript.

Serializer for ID-based fraud scan request. Supports optional face image for combined ID + face verification. Backward compatible - image field is optional.

Response Body

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/fraud/id-scan/" \  -H "Content-Type: application/json" \  -d '{    "id_type": "bvn",    "id_number": "22334",    "search_mode": "partial",    "date_from": "2023-01-01",    "date_to": "2024-01-31",    "fraud_category": "bank",    "verified_only": true  }'
{  "status": "success",  "message": "ID scan completed successfully",  "response_code": "00",  "detail": "Scan completed successfully",  "meta": {},  "billing_info": {    "was_charged": true,    "amount": "50.00",    "currency": "NGN",    "note": "Wallet charged 50.00 NGN",    "source": "wallet"  },  "verification": {    "status": "VERIFIED",    "reference": "4ebda4e1-48e8-43b1-8f3e-7549388c6458",    "verification_id": "e142197c-4cda-4f81-8ed5-7e6dcfbf2cf3"  },  "reference_id": "FS-0A1B2C3D4E5F",  "transaction_id": "11730c7e-9e86-45ba-ab25-b0b09ecff700",  "verification_status": "verified",  "data": {    "scan_id": "ID-8F3A2B4C9D1E",    "timestamp": "2024-01-15T10:30:00Z",    "id_type": "bvn",    "id_number": "22334455667",    "search_mode": "exact",    "is_in_fraud_bank": false,    "total_reports": 0,    "verified_reports": 0,    "unverified_reports": 0,    "matched_reports": [],    "risk_level": "LOW",    "risk_score": 0,    "fraud_categories": [],    "total_fraud_amount": null,    "currency": "NGN",    "first_reported_date": null,    "last_reported_date": null,    "recommendations": [      " No fraud reports found in database",      "🟢 ID appears clean - proceed with standard verification",      "📊 Continue standard monitoring"    ],    "processing_time_ms": 45  }}
Response Codes & Statuses: Prembly API responses include custom response_code values (e.g., 00 Success, 01 Not Found, 02 Unavailable).
View Response Codes Guide
Prembly Slack Community

Join our developer Slack channel for real-time integration support, engineering updates, and direct Q&A with the Prembly team.

Join Slack Channel

Scan a face for fraud POST

Perform comprehensive fraud detection analysis on a face image. This endpoint performs multi-layered fraud detection: **1. Multiple ID Detection (Nigerian Fraud Pattern)** - Checks if the same face appears in multiple national IDs (BVN, NIN, Passport) - Common fraud pattern in Nigeria where identity thieves create multiple IDs with same face - Returns all matched identities with confidence scores **2. Fraud Bank Database Matching** - Matches face against verified fraud reports in the fraud bank - Returns fraud history including categories, amounts, and report details - Shows verified fraud cases and unverified reports **3. General Identity Analysis** - Provides overall identity confidence score - Checks consistency of identity information across sources - Generates security flags and actionable recommendations **Risk Scoring:** - Overall risk score (0-100) calculated from multiple factors - Risk level: LOW, MEDIUM, HIGH, CRITICAL - Fraud detection flag based on thresholds and patterns **Use Cases:** - Customer onboarding KYC verification - Transaction approval fraud checks - Account takeover prevention - Identity theft detection - Compliance and regulatory reporting **Note:** Image search functionality uses placeholder data for testing. Production integration with biometric matching service required. **Authentication:** Requires X-API-Key header with valid API key (sandbox or live).

Screen a transaction POST

Scores a transaction against your configured rules and returns a risk assessment. This is the entry point to transaction screening — everything else in this section reads results it produced. The response carries the score (`risk_score`, `risk_level`, `fraud_probability`), the outcome (`status`), and which of your rules fired (`rules_triggered`, `rules_triggered_count`). Keep `internal_reference` — it is how you fetch the transaction again later. Returns `201`: screening creates a stored transaction record, it does not merely evaluate one. Send a sandbox key (`test_sk_` / `test_pk_`) to screen without affecting your production data; sandbox results are filtered out of the live transaction list by the `mode` parameter.