Upload an Excel file containing multiple records for bulk fraud scan processing.
This endpoint accepts Excel files (.xlsx, .xls) with face scan or ID scan data. Records are validated, processed in the background using Celery, and results are stored in S3 for download.
Supported Scan Types:
face_scan: Face image fraud detectionid_scan: Identity document verification
Processing Flow:
- Upload Excel file with scan_type parameter
- File is validated for format and required columns
- Records are validated against scan type requirements
- Background task processes records asynchronously
- Results file is generated and uploaded to S3
- Status updates available via list/detail endpoints
Status Transitions:
pending: Initial upload, queued for processingprocessing: Background task actively processing recordscompleted: All records processed, results availablefailed: Processing failed (with error message)
Excel Format for Face Scan:
| Column Name | Required | Description | Example |
|---|---|---|---|
| image_url | Yes | URL to face image | https://cdn.example.com/face1.jpg |
| reference_id | No | Your reference ID | USER-001 |
| check_fraud_bank | No | Check fraud database (yes/no) | yes |
| check_multiple_ids | No | Check for multiple IDs (yes/no) | yes |
| similarity_threshold | No | Similarity threshold (0.0-1.0) | 0.85 |
Sample Face Scan Excel:
| image_url | reference_id | check_fraud_bank | check_multiple_ids | similarity_threshold |
|---|---|---|---|---|
| https://cdn.example.com/images/user1.jpg | USER-001 | yes | yes | 0.85 |
| https://cdn.example.com/images/user2.jpg | USER-002 | yes | no | 0.90 |
| https://cdn.example.com/images/user3.jpg | USER-003 | no | yes | 0.80 |
| https://cdn.example.com/images/user4.jpg | USER-004 | yes | yes | 0.75 |
Excel Format for ID Scan:
| Column Name | Required | Description | Example |
|---|---|---|---|
| id_type | Yes | Type of ID | bvn, nin, passport, drivers_license |
| id_number | Yes | ID number | 22334455667 |
| reference_id | No | Your reference ID | TXN-001 |
| image_url | No | URL to face image | https://example.com/face.jpg |
| search_mode | No | Search mode (exact/partial) | exact |
Sample ID Scan Excel:
| id_type | id_number | reference_id | search_mode | image_url |
|---|---|---|---|---|
| bvn | 22334455667 | TXN-001 | exact | https://cdn.example.com/face1.jpg |
| nin | 12345678901 | TXN-002 | exact | |
| passport | A12345678 | TXN-003 | partial | |
| drivers_license | DL-9876543210 | TXN-004 | exact | https://cdn.example.com/face2.jpg |
| vnin | 98765432109876 | TXN-005 | exact |
Valid ID Types:
bvn: Bank Verification Number (11 digits)nin: National Identity Number (11 digits)vnin: Virtual National Identity Number (16 digits)passport: International Passport Numberdrivers_license: Driver's License Numberphone: Phone Number
Validation:
- Excel must have all required columns for the scan type
- At least one valid record must be present
- Invalid records are reported in error file
- Valid records are processed, invalid ones skipped
Background Processing:
- Uses Celery for asynchronous processing
- Processes up to 1000 records at a time
- Progress updated in database
- Results uploaded to S3 when complete
Results:
- Results file available via
result_file_urlin response - Contains all scan results with detailed fraud analysis
- Download link expires based on S3 configuration
- Includes processing metadata (total, success, failed counts)
Error Handling:
- Invalid Excel format returns 400 with error details
- Empty file returns 400 with message
- All-invalid records returns 400 with error file
- Processing errors update status to 'failed'
- Error file contains row-specific validation errors
Requirements:
- Organisation must be verified
- Valid Excel file (.xlsx or .xls)
- Sufficient wallet balance for processing
- Proper column headers for scan type
Authorization
ApiKeyAuth In: header
Request Body
multipart/form-data
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
curl -X POST "https://example.com/api/v1/fraud/bulk-scan/upload/" \ -F scan_type="face_scan" \ -F file="null"{ "status": true, "message": "Bulk scan uploaded successfully. Processing has started.", "data": { "bulk_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef", "scan_type": "face_scan", "status": "pending", "total_records": 150, "processed_records": 0, "success_count": 0, "error_count": 0, "uploaded_by": "user@example.com", "uploaded_at": "2026-01-07T10:30:00Z", "completed_at": null, "result_file_url": null, "error_file_url": null }}response_code values (e.g., 00 Success, 01 Not Found, 02 Unavailable).Join our developer Slack channel for real-time integration support, engineering updates, and direct Q&A with the Prembly team.
Join Slack ChannelGet a bulk fraud scan GET
Retrieve detailed information about a specific bulk fraud scan. **Use this endpoint to:** - Check processing status of a bulk scan - Get download links for result and error files - Monitor processing progress (processed_records vs total_records) - View success/error counts - Access error messages if processing failed **Response Includes:** - Complete scan details (type, status, counts) - File URLs (results, errors, original upload) - Processing timestamps (uploaded_at, completed_at) - User information (uploaded_by) - Error details if status is 'failed' **Status Check:** - Poll this endpoint to monitor processing progress - When status changes to 'completed', result_file_url is available - If status is 'failed', check error_message for details
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).