REST API Contract & Specifications

Shared communication protocol between external websites, SMS Bridge Pro, and native Android physical SIM nodes.

API Base URL: /api/v1/
Unified Workflow Architecture
  1. External Website: Authenticates via X-API-Key and X-API-Secret, calls POST /website/sms with recipient, message, priority, and optional idempotency key.
  2. Main Server: Validates quota and stores job as pending in MySQL.
  3. Android Device: Authenticates via Bearer <device_token>, polls GET /device/jobs.
  4. Android Device: Atomically claims a job via POST /device/jobs/{id}/claim to guarantee single-execution.
  5. Physical Hardware: SmsManager sends SMS via selected SIM 1 or SIM 2. BroadcastReceivers track carrier transmission and delivery PDU.
  6. Synchronization: APK reports final status (sent, failed, or delivery_confirmed) back via POST /device/jobs/{id}/result.
1. External Website Integration Endpoints
POST /website/sms
Auth: Website API Key + Secret

Enqueues an SMS to be sent through the phone gateway. Includes duplicate event protection via external_event_id.

Required Headers:
Content-Type: application/json X-API-Key: wsb_live_a1b2c3d4e5f67890 X-API-Secret: sec_live_9876543210fedcba
Request Body:
{ "recipient": "+14155552671", "message": "Your verification code is 849201. Valid for 5 minutes.", "priority": 8, "external_event_id": "order_verification_10948" }
Response (201 Created):
{ "success": true, "message": "SMS job accepted and enqueued.", "data": { "job_id": 142, "job_uuid": "job_9a8b7c6d5e4f3a2b1c", "external_event_id": "order_verification_10948", "recipient": "+14155552671", "parts_count": 1, "status": "pending", "is_duplicate": false, "created_at": "2026-10-25 03:40:00" }, "timestamp": "2026-10-25T03:40:00Z" }
cURL Example:
curl -X POST "/api/v1/website/sms" \ -H "Content-Type: application/json" \ -H "X-API-Key: wsb_live_a1b2c3d4e5f67890" \ -H "X-API-Secret: sec_live_9876543210fedcba" \ -d '{"recipient":"+14155552671","message":"Test SMS","priority":5}'
GET /website/status
Auth: Website API Key + Secret

Check real-time delivery status of any previously dispatched job.

Query Parameters (Provide at least one):
  • job_id: Integer ID returned upon queueing (e.g. ?job_id=142)
  • job_uuid: String UUID (e.g. ?job_uuid=job_9a8b...)
  • external_event_id: Your system's unique event ID (e.g. ?external_event_id=order_10948)
Response (200 OK):
{ "success": true, "message": "SMS job status retrieved.", "data": { "job_id": 142, "job_uuid": "job_9a8b7c6d5e4f3a2b1c", "external_event_id": "order_verification_10948", "recipient": "+14155552671", "status": "delivery_confirmed", "attempt_count": 1, "error_message": null, "carrier_message_id": "carrier_pdu_7741", "created_at": "2026-10-25 03:40:00", "claimed_at": "2026-10-25 03:40:05", "sent_at": "2026-10-25 03:40:07", "delivered_at": "2026-10-25 03:40:11" }, "timestamp": "2026-10-25T03:40:12Z" }
2. Android APK Gateway Endpoints
POST /device/register
Auth: Open / Device Pairing

Pairs an Android device with the server, returning a permanent Bearer access token.

Request Body:
{ "device_uuid": "android-hw-uuid-550e8400", "device_name": "Samsung Galaxy S23 (Gateway 1)", "phone_number": "+14155559999", "model": "SM-S911B", "android_version": "14", "app_version": "1.0.0" }
Response (201 Created):
{ "success": true, "message": "Device registered successfully.", "data": { "device_id": 4, "device_uuid": "android-hw-uuid-550e8400", "device_name": "Samsung Galaxy S23 (Gateway 1)", "device_token": "dev_tok_8f1b3c94d0e7a256193f4e..." }, "timestamp": "2026-10-25T03:40:15Z" }
POST /device/heartbeat
Auth: Bearer <device_token>

Transmits phone telemetry (battery, network, active SIM) and fetches server instructions.

Request Body:
{ "battery_level": 94, "is_charging": 1, "network_type": "WIFI", "sim_operator": "T-Mobile US", "sim_slot_count": 2, "active_sim_slot": 0 }
Response (200 OK):
{ "success": true, "message": "Heartbeat acknowledged.", "data": { "device_id": 4, "emergency_stop": false, "polling_interval_seconds": 5, "server_time": "2026-10-25T03:40:20Z" }, "timestamp": "2026-10-25T03:40:20Z" }
GET /device/jobs
Auth: Bearer <device_token>

Fetches authorized pending jobs ordered by priority descending.

Response (200 OK):
{ "success": true, "message": "Pending jobs retrieved.", "data": { "count": 1, "jobs": [ { "id": 142, "job_uuid": "job_9a8b7c6d5e4f3a2b1c", "external_event_id": "order_verification_10948", "recipient": "+14155552671", "message": "Your verification code is 849201. Valid for 5 minutes.", "priority": 8, "parts_count": 1, "created_at": "2026-10-25 03:40:00", "source_website": "Demo Store E-Commerce" } ] }, "timestamp": "2026-10-25T03:40:25Z" }
POST /device/jobs/{id}/claim
Auth: Bearer <device_token>

Claims a job atomically in the database to prevent duplicate sending across multiple phones.

Response (200 OK):
{ "success": true, "message": "Job claimed successfully.", "data": { "job_id": 142, "device_id": 4, "status": "claimed", "claimed_at": "2026-10-25T03:40:30Z" }, "timestamp": "2026-10-25T03:40:30Z" }
POST /device/jobs/{id}/result
Auth: Bearer <device_token>

Synchronizes sending or delivery results back to the main server.

Request Body:
{ "status": "sent", "carrier_message_id": "carrier_tx_99812", "sim_slot": 0, "parts_sent": 1, "attempt_duration_ms": 680, "error_message": null }
Response (200 OK):
{ "success": true, "message": "Job execution result synchronized successfully.", "data": { "job_id": 142, "status": "sent", "synchronized_at": "2026-10-25T03:40:35Z" }, "timestamp": "2026-10-25T03:40:35Z" }
Structured Error Codes Reference
HTTP Code Error Code Description
401UNAUTHORIZEDMissing or invalid API credentials or device token.
403FORBIDDENIP restriction failed or device/website suspended.
404NOT_FOUNDResource or job ID not found.
409CLAIM_FAILEDJob already claimed by another gateway node.
422VALIDATION_FAILEDMissing required fields (recipient, message).
429QUOTA_EXCEEDEDWebsite daily SMS quota limit reached.
503SERVICE_SUSPENDEDEmergency kill-switch is active.