Developer REST API Reference

All REST API calls must be transmitted over encrypted HTTPS requests. Authenticate your API request by including your account API secret key in the HTTP Authorization header using the Bearer scheme.

Enqueues an outbound transactional SMS for immediate background transmission via your connected Android gateway smartphones.

{
    "to": "+919876543210",
    "message": "Your order #1042 has been dispatched!",
    "type": "transactional",
    "priority": 5,
    "gateway_id": 2, // (Optional) Target specific paired device ID
    "gateway_uuid": "GW-20260824-A1B2C3" // (Optional alternative to gateway_id)
}

{
    "success": true,
    "message_id": "MSG-20260823-A1B2C3D4",
    "status": "queued",
    "gateway_assigned": true
}

curl -X POST "https://sms.hostgeeks.in/api/v1/send" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "9876543210",
    "message": "Your order #1042 has been dispatched!",
    "type": "transactional",
    "priority": 5
  }'

Enqueues up to 1,000 personalized or broadcast SMS messages in a single atomic API request. The gateway automatically load-balances and processes the queue across your connected Android SIM devices.

{
  "messages": [
    {
      "to": "+919876543210",
      "message": "Hi Alice, order #1042 has been dispatched!"
    },
    {
      "to": "+919876543211",
      "message": "Hi Bob, order #1043 has been dispatched!"
    }
  ],
  "priority": 5,
  "gateway_id": 2
}

{
  "recipients": [
    "+919876543210",
    "+919876543211",
    "+919876543212"
  ],
  "message": "Flash Sale Alert! Enjoy 20% OFF today only with code FLASH20.",
  "priority": 5
}

{
  "success": true,
  "batch_id": "BATCH-20260825-9F3A1C",
  "total_submitted": 2,
  "queued_count": 2,
  "failed_count": 0,
  "gateway_id": 5,
  "messages": [
    {
      "index": 0,
      "message_id": "MSG-20260825-A1B2C3D4",
      "recipient": "+919876543210",
      "status": "queued"
    },
    {
      "index": 1,
      "message_id": "MSG-20260825-E5F6G7H8",
      "recipient": "+919876543211",
      "status": "queued"
    }
  ]
}

curl -X POST "https://sms.hostgeeks.in/api/v1/bulk-send" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "to": "+919876543210", "message": "Hi Alice, order #101 dispatched!" },
      { "to": "+919876543211", "message": "Hi Bob, order #102 dispatched!" }
    ],
    "priority": 5
  }'

Generates a cryptographically secure numeric OTP code, hashes it in the database, and dispatches via high-priority queue. Plaintext OTP is never returned in API responses for security.

{
    "to": "9876543210",
    "digits": 6,
    "ttl": 300
}

{
    "success": true,
    "request_id": "OTP-998877665544",
    "status": "queued",
    "expires_in": 300
}

curl -X POST "https://sms.hostgeeks.in/api/v1/otp/send" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "9876543210",
    "digits": 6,
    "ttl": 300
  }'

Validates user-submitted numeric OTP code against the stored cryptographic hash.

{
    "request_id": "OTP-998877665544",
    "otp": "123456"
}

{
    "success": true,
    "request_id": "OTP-998877665544",
    "verified": true,
    "message": "OTP successfully verified."
}

curl -X POST "https://sms.hostgeeks.in/api/v1/otp/verify" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "OTP-998877665544",
    "otp": "123456"
  }'

Retrieves real-time dispatch and SIM network status telemetry for any queued or delivered SMS.

{
    "success": true,
    "message_id": "MSG-20260823-A1B2C3D4",
    "status": "delivered",
    "dispatched_at": "2026-08-24 16:42:01",
    "sim_slot": "SIM 1 (Airtel 4G)"
}

curl -X GET "https://sms.hostgeeks.in/api/v1/status?message_id=MSG-20260823-A1B2C3D4" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Control when your SMS will reach your recipients, allowing you to perfectly time promotions, critical alerts, and appointment reminders by scheduling your messages in advance. Pass the scheduled_at parameter in ISO-8601 or standard YYYY-MM-DD HH:MM:SS format.

{
    "success": true,
    "message_id": "MSG-20260825-9A8B7C",
    "status": "scheduled",
    "scheduled_at": "2026-08-26 09:00:00",
    "gateway_assigned": true
}

curl -X POST "https://sms.hostgeeks.in/api/v1/send" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+919876543210",
    "message": "Reminder: Your appointment is scheduled for tomorrow at 10:00 AM.",
    "scheduled_at": "2026-08-26 09:00:00"
  }'

Take control of your privacy with our end-to-end encrypted SMS feature. Safeguard your messages from prying eyes, ensuring absolute confidentiality using the military grade AES-256-GCM authenticated encryption algorithm. When enabled, message bodies are encrypted at rest with distinct initialization vectors (IV) and authentication tags.

{
    "success": true,
    "message_id": "MSG-20260825-E4F5D6",
    "status": "queued",
    "encrypted": true,
    "encryption_algo": "AES-256-GCM",
    "gateway_assigned": true
}

curl -X POST "https://sms.hostgeeks.in/api/v1/send" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+919876543210",
    "message": "Confidential statement code: ACCT-9821-X9",
    "encrypt": true
  }'

If you want to build advanced integrations, we support callback URLs. The SMS Gateway platform can automatically forward SMS messages received on your Android phone to your server using a callback URL which you provide. Every webhook payload is signed with an HMAC-SHA256 signature in the X-SMS-Signature header.

{
  "event": "sms_received",
  "timestamp": "2026-08-25T12:45:00Z",
  "data": {
    "message_id": "IN-20260825-9A1B2C",
    "sender": "+919876543210",
    "recipient": "+919876543210",
    "message": "Yes, please confirm my order!",
    "sim_slot": 1,
    "gateway_name": "Samsung Galaxy S22",
    "received_at": "2026-08-25 12:45:00"
  }
}

curl -X POST "https://your-server.com/webhook/sms" \
  -H "Content-Type: application/json" \
  -H "X-SMS-Event: sms_received" \
  -H "X-SMS-Signature: 8f4a1c5d9e..." \
  -d '{
    "event": "sms_received",
    "timestamp": "2026-08-25T12:45:00Z",
    "data": {
      "message_id": "IN-20260825-9A1B2C",
      "sender": "+919876543210",
      "recipient": "+919876543210",
      "message": "Yes, please confirm my order!",
      "received_at": "2026-08-25 12:45:00"
    }
  }'

Connect your workflow with thousands of other apps with the power of Zapier, Make, or n8n. For example, you can set up an automation to send personalized SMS messages each time someone makes an order from your Shopify store or each time a new row is added to a Google spreadsheet.

Send SMS messages without going over your mobile carrier limitations. If you set a rate (e.g. 3 messages per minute), the gateway will automatically queue up your messages and send them at a spaced rate of 1 message per 20 seconds, completely avoiding telecom spam flags.