Developer API Documentation

1. Overview & Base URL

The Zuribu REST API allows you to send SMS messages, query queue telemetry, manage webhooks, and inspect Android worker phone fleet health via standard HTTPS requests.

Base Endpoint

http://localhost:8000/v1

2. Authentication

Authenticate API requests by passing your Developer Application credentials in custom HTTP headers:

Header	Type	Description
X-API-Key	string	Your public application identifier key.
X-API-Secret	string	Your private application secret token.

3. Send Outbound SMS POST

Enqueue one or multiple SMS messages for immediate delivery across active Android worker phones and SIM cards.

Request Sample (CURL)

Response Payload (201 Created) JSON

{
  "id": "msg_9f8b2c1a4e5d6f78",
  "status": "queued",
  "recipients_count": 1,
  "created_at": "2026-08-22T12:00:00.000Z"
}

4. List & Query Messages GET

Query paginated SMS dispatch history, filter by delivery state, or inspect millisecond worker latency.

Query Sample (CURL)

5. Message Lifecycle & States

queued

Message stored in database and awaiting dispatch to an available phone worker.

dispatched

Payload pushed to Android worker phone over WebSocket / Reverb.

sent

Worker phone injected SMS into cellular radio and transmitted to cell tower.

delivered

Carrier network confirmed final delivery to recipient handset.

failed

Carrier rejection, no cellular signal, SIM balance exhaustion, or radio error.

6. Inbound Webhooks & Events

Register webhook callback URLs to receive immediate HTTP POST notifications when SMS events occur on connected phones.

Incoming SMS Webhook Payload (sms:received) POST Body

{
  "event": "sms:received",
  "data": {
    "sender": "+8801987654321",
    "text": "YES I CONFIRM ORDER #49102",
    "sim_slot": 1,
    "carrier_name": "Grameenphone",
    "received_at": "2026-08-22T12:00:00.000Z",
    "device_id": "8ZLxbdjkK5U4mHA1xJwR"
  },
  "timestamp": "2026-08-22T12:00:00.184Z"
}

7. Signature Verification

Zuribu includes a cryptographic HMAC-SHA256 signature in the X-Zuribu-Signature-256 header. Verify this header to ensure requests originate from your gateway.

Verification Sample (CURL)

8. Errors & Status Codes

Status	Meaning	Description
200 OK	Success	Request processed successfully.
201 Created	Message Queued	SMS successfully queued for dispatch.
400 Bad Request	Invalid Payload	Missing required text or invalid phone formatting.
401 Unauthorized	Authentication Failed	Invalid API Key or Secret header.
403 Forbidden	IP Restricted	Client IP is not in Developer App whitelist.
404 Not Found	Resource Missing	Requested Message ID or Webhook ID not found.