Prembly
GuidesAPI Reference
Fraud LensFraud ScanGet a bulk fraud scan GET
GET
/api/v1/fraud/bulk-scan/{bulk_id}/

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

Authorization

ApiKeyAuth
X-API-Key<token>

In: header

Path Parameters

bulk_id*string

Unique identifier for the bulk scan

Formatuuid

Response Body

application/json

curl -X GET "https://example.com/api/v1/fraud/bulk-scan/497f6eca-6276-4993-bfeb-53cbbbba6f08/"

{  "status": true,  "message": "Bulk scan details retrieved successfully",  "data": {    "bulk_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",    "scan_type": "face_scan",    "status": "completed",    "total_records": 150,    "processed_records": 150,    "success_count": 145,    "error_count": 5,    "uploaded_by": "user@example.com",    "uploaded_at": "2026-01-07T10:30:00Z",    "completed_at": "2026-01-07T10:45:00Z",    "result_file_url": "https://s3.amazonaws.com/bucket/results_20260107.xlsx",    "error_file_url": null,    "error_message": null  }}

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

List bulk fraud scans GET

Retrieve a paginated list of all bulk fraud scans for your organisation. **Features:** - Standard pagination (page, page_size parameters) - Filter by scan_type (face_scan, id_scan) - Filter by status (pending, processing, completed, failed) - Ordered by most recent first (uploaded_at DESC) **Status Meanings:** - `pending`: Queued for processing, not yet started - `processing`: Currently being processed in background - `completed`: Successfully processed, results available - `failed`: Processing failed, see error_message **Response Fields:** - `bulk_id`: Unique identifier for the bulk scan - `scan_type`: Type of scan (face_scan or id_scan) - `status`: Current processing status - `total_records`: Total number of records in upload - `processed_records`: Number of records processed so far - `success_count`: Number of successfully processed records - `error_count`: Number of records with errors - `result_file_url`: Download link for results (available when completed) - `error_file_url`: Download link for validation errors (if any) - `uploaded_by`: Email of user who uploaded - `uploaded_at`: Timestamp of upload - `completed_at`: Timestamp of completion (null if not completed) **Pagination:** - Default page_size: 20 - Max page_size: 100 - Returns: count, next, previous, results

Upload a bulk fraud scan POST

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 detection - `id_scan`: Identity document verification **Processing Flow:** 1. Upload Excel file with scan_type parameter 2. File is validated for format and required columns 3. Records are validated against scan type requirements 4. Background task processes records asynchronously 5. Results file is generated and uploaded to S3 6. Status updates available via list/detail endpoints **Status Transitions:** - `pending`: Initial upload, queued for processing - `processing`: Background task actively processing records - `completed`: All records processed, results available - `failed`: 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 Number - `drivers_license`: Driver's License Number - `phone`: 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_url` in 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