Cross-Platform Courier Fraud Checker & Real-Time Telemetry API (Android, iOS, Flutter, React Native)
# Cross-Platform Courier Fraud Checker & Real-Time Telemetry API
Production-ready integration guide for Mobile Application Developers (Android, iOS, Flutter, React Native) and e-commerce merchant apps to verify customer delivery reputation across Bangladesh's premier couriers (**Steadfast, Pathao, Carrybee, RedX, Paperfly**).
All queries use high-speed residential proxy obfuscation and multi-courier API rotation to ensure zero IP throttling, zero courier blocking, and instant live telemetry directly on mobile devices.
---
### 1. Authentication & Dedicated App Tokens
Every mobile application request must be signed with an App API Token generated in the **Pixahunt Mobile Apps Management Console** (`/admin/apps`).
```http
POST /api/v1/apps/courier-fraud/check HTTP/1.1
Host: pixahunt.com
X-App-Token: pxh_app_your_token_here
X-App-Platform: android
X-App-Package: com.pixahunt.courierfraudchecker
X-App-Version: 1.0.0
Content-Type: application/json
Accept: application/json
```
*You may also pass the token via standard `Authorization: Bearer pxh_app_...` header or `?app_token=...` parameter.*
---
### 2. Single Number Fraud Check (Real-Time Telemetry)
Triggered when merchant pastes a customer phone number, copies from clipboard, or when an incoming call is received via Android Caller ID / Call Screening Service.
- **Method**: `POST` (or `GET`)
- **Primary Endpoint**: `/api/v1/apps/courier-fraud/check`
- **Flexible Alias**: `/api/apps/v1/courier-fraud/check`
#### Request Payload
```json
{
"phone": "01701002944"
}
```
#### JSON Response (200 OK)
```json
{
"success": true,
"phone": "01701002944",
"app_client": {
"app_name": "Apps Fraud Checker",
"platform": "android",
"total_requests": 42
},
"caller_id": {
"headline": "নিরাপদ গ্রাহক (Safe Buyer) — 100% সাকসেস",
"rate_label": "100% (1/1 ডেলিভার্ড, 0 রিটার্ন)",
"badge": {
"tag": "নিরাপদ গ্রাহক (Safe Buyer)",
"color": "emerald",
"icon": "shield_check",
"action_recommendation_bn": "নির্দ্বিধায় পার্সেল পাঠানো যায়। ডেলিভারি রেট চমৎকার।",
"action_recommendation_en": "Safe to dispatch. High delivery acceptance history.",
"alert_level": "LOW"
}
},
"summary": {
"total_parcels": 1,
"total_delivered": 1,
"total_returned": 0,
"total_cancelled": 0,
"success_rate": 100,
"risk_level": "safe"
},
"couriers": {
"steadfast": {
"name": "Steadfast Courier",
"total": 1,
"delivered": 1,
"returned": 0,
"success_rate": 100,
"status": "live"
},
"pathao": {
"name": "Pathao Courier",
"total": 0,
"delivered": 0,
"returned": 0,
"success_rate": 0,
"status": "live"
},
"carrybee": {
"name": "Carrybee Courier",
"total": 0,
"delivered": 0,
"returned": 0,
"success_rate": 0,
"status": "live"
},
"redx": {
"name": "RedX Delivery",
"total": 0,
"delivered": 0,
"returned": 0,
"success_rate": 0,
"status": "live"
},
"paperfly": {
"name": "Paperfly Courier",
"total": 0,
"delivered": 0,
"returned": 0,
"success_rate": 0,
"status": "live"
}
},
"hit_count": 3,
"cached": true,
"last_checked_at": "2026-10-27 10:36:00"
}
```
---
### 3. Batch Check Endpoint (Bulk Order Verification)
Used by order management dashboards, dispatch teams, and warehouse fulfillment apps to scan up to 50 phone numbers in a single API roundtrip.
- **Method**: `POST`
- **Endpoint**: `/api/v1/apps/courier-fraud/batch-check`
#### Request Payload
```json
{
"phones": [
"01701002944",
"01812345678",
"01999887766"
]
}
```
#### JSON Response (200 OK)
```json
{
"success": true,
"total_submitted": 3,
"total_processed": 3,
"app_name": "Apps Fraud Checker",
"results": [
{
"phone": "01701002944",
"status": "verified",
"total_parcels": 12,
"delivered": 11,
"returned": 1,
"cancelled": 0,
"success_rate": 91.67,
"risk_level": "safe",
"verdict_bn": "নিরাপদ গ্রাহক (উচ্চ ডেলিভারি সফলতার হার)",
"verdict_en": "Safe Buyer (Highly Reliable)"
}
]
}
```
---
### 4. Active Couriers & Network Status Endpoint
Retrieves the real-time operational status, brand logos, and connectivity of all integrated courier partners.
- **Method**: `GET`
- **Endpoint**: `/api/v1/apps/courier-fraud/providers`
#### JSON Response (200 OK)
```json
{
"success": true,
"count": 5,
"providers": [
{ "name": "Steadfast Courier", "slug": "steadfast", "is_active": true },
{ "name": "Pathao Courier", "slug": "pathao", "is_active": true },
{ "name": "Carrybee Courier", "slug": "carrybee", "is_active": true },
{ "name": "RedX Delivery", "slug": "redx", "is_active": true },
{ "name": "Paperfly Courier", "slug": "paperfly", "is_active": true }
]
}
```
---
### 5. App Telemetry & Network Stats Endpoint
Provides real-time aggregated metrics across all verified delivery records and fraud incidents in Bangladesh.
- **Method**: `GET`
- **Endpoint**: `/api/v1/apps/courier-fraud/stats`
#### JSON Response (200 OK)
```json
{
"success": true,
"app_name": "Apps Fraud Checker",
"total_requests_by_app": 1420,
"total_database_records": 48210,
"safe_buyers_count": 39500,
"risky_buyers_count": 8710
}
```
---
### 6. App Version Control & In-App Forced Update
Enables compiled mobile applications to check for new releases on startup, prompt users to upgrade, or enforce mandatory updates before allowing further app usage.
- **Method**: `GET`
- **Primary Endpoint**: `/api/v1/apps/courier-fraud/version`
- **Global Alias**: `/api/apps/v1/version`
#### Request Headers / Query Parameters
```http
GET /api/v1/apps/courier-fraud/version HTTP/1.1
Host: pixahunt.com
X-App-Token: pxh_app_your_token_here
X-App-Package: com.pixahunt.courierfraudchecker
X-App-Version: 1.0.0
X-App-Platform: android
```
#### JSON Response (200 OK)
```json
{
"success": true,
"app_name": "Apps Fraud Checker",
"package_id": "com.pixahunt.courierfraudchecker",
"platform": "android",
"current_installed_version": "1.0.0",
"latest_version": "1.2.0",
"min_version": "1.1.0",
"is_update_available": true,
"is_force_update": true,
"update_url": "https://play.google.com/store/apps/details?id=com.pixahunt.courierfraudchecker",
"release_notes": "Added instant courier fraud scoring, auto background cache, and biometric authentication.",
"checked_at": "2026-10-27T17:00:00Z"
}
```
---
### 7. Android Kotlin Implementation (Retrofit + Coroutines)
```kotlin
import retrofit2.Response
import retrofit2.http.*
interface PixahuntCourierApi {
@POST("api/v1/apps/courier-fraud/check")
suspend fun checkReputation(
@Header("X-App-Token") appToken: String,
@Header("X-App-Platform") platform: String = "android",
@Header("X-App-Package") pkg: String,
@Header("X-App-Version") version: String,
@Body request: Map
): Response
@GET("api/v1/apps/courier-fraud/version")
suspend fun checkAppVersion(
@Header("X-App-Token") appToken: String,
@Header("X-App-Version") version: String,
@Header("X-App-Package") pkg: String
): Response
}
```
---
### 8. Flutter / Dart Implementation (Dio / http)
```dart
import 'dart:convert';
import 'package:http/http.dart' as http;
Future> checkCourierFraud(String phone) async {
final url = Uri.parse('https://pixahunt.com/api/v1/apps/courier-fraud/check');
final response = await http.post(
url,
headers: {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-App-Token': 'pxh_app_your_token_here',
'X-App-Platform': 'flutter',
'X-App-Package': 'com.pixahunt.courierfraudchecker',
'X-App-Version': '1.0.0',
},
body: jsonEncode({'phone': phone}),
);
return jsonDecode(response.body);
}
```
---
### 9. HTTP Status Codes & Error Handling
Standard HTTP response codes returned by the Pixahunt Mobile Apps API:
- `200 OK`: Telemetry lookup completed successfully.
- `401 Unauthorized`: Missing, expired, or deactivated `X-App-Token`.
- `422 Unprocessable Entity`: Invalid Bangladeshi phone number format. Must be standard 11 digits `01XXXXXXXXX`.
- `429 Too Many Requests`: Rate limit reached.
- `500 Internal Error`: Upstream courier communication failure (gracefully handled with fallback).