REST API Documentation - VeloQuip SMS

REST API Documentation 🔌

Complete integration specifications, code snippets, and endpoints for SMS & Voice gateway services.

API v2.0 Live JSON • HTTPS

Modern REST Clean URLs & Guaranteed Backward Compatibility ACTIVE

All VeloQuip SMS API endpoints now use modern clean URLs without the .php extension (e.g. POST https://veloquipsms.top/api/send_sms). Existing integrations are never broken: all endpoints with .php (e.g. /api/send_sms.php) remain permanently active and fully supported.

Jump to: POST Send SMS GET SMS Balance POST Register Sender GET Approved Senders POST Sender Status POST Voice Broadcast

POST Send SMS Broadcast

Transactional & Promotional

Dispatch single or bulk SMS messages to one or multiple recipients in real time using your approved Sender ID.

POSThttps://veloquipsms.top/api/send_sms Legacy: /api/send_sms.php

Request Headers

HTTP Headers

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
Accept: application/json

JSON Request Body Parameters

Field	Type	Status	Description
recipient	Array<string>	Required	Array of recipient phone numbers in international format without plus sign (e.g. `["233241234567", "233501234567"]`).
sender	string	Required	Your approved Sender ID registered to your account (max 11 characters alphanumeric).
message	string	Required	SMS text content. 1 unit = 160 characters for standard GSM encoding.

Request Body Example

JSON Payload

{
  "recipient": ["233241234567", "233501234567"],
  "sender": "VeloQuip",
  "message": "Your verification code is 481920. Valid for 10 minutes."
}

Server Responses

200 OK (Success)

{
  "status": "success",
  "code": "2000",
  "message": "messages sent successfully",
  "data": {
    "campaign_id": "A59CCB70-662D-45EF",
    "total_sent": 2,
    "credit_used": 2,
    "credit_left": 1483
  }
}

400 Error Response

{
  "status": "error",
  "code": "4001",
  "message": "Insufficient SMS balance"
}

GET Check SMS & Cash Balance

Account Inquiry

Retrieve your real-time wallet unit balances, cash balance, and aggregate platform dispatch statistics. The sms_balance field returns your total usable SMS credits (combining active expiry credits and non-expiring credits).

GEThttps://veloquipsms.top/api/balance Legacy: /api/balance.php

Request Headers & Query Params

Header: Authorization: Bearer YOUR_API_KEY

Query: ?key=YOUR_API_KEY

Success Response (200 OK)

JSON Response

{
  "status": "success",
  "code": "2000",
  "data": {
    "sms_balance": 1483,
    "cash_balance": 50.00,
    "total_sent": 517,
    "expiry_balance": 1000,
    "non_expiry_balance": 483
  }
}

POST Register / Request Sender ID

NCA Compliance

Register a new Sender ID directly via API. The request is submitted to the telecommunications network gateway and National Communications Authority (NCA) compliance verification. If pre-approved or already verified upstream, it is activated immediately.

POSThttps://veloquipsms.top/api/create_sender Legacy: /api/create_sender.php

Note: You can also use POST https://veloquipsms.top/api/sender_ids interchangeably.

Request Headers

HTTP Headers

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
Accept: application/json

JSON Request Body Parameters

Field	Type	Status	Description
sender_name	string	Required	Desired Sender ID. Between 3 and 11 characters (letters, numbers, spaces, dots, hyphens). Must contain letters per NCA regulations (cannot be purely numeric).
purpose	string	Required	Intended business use case or message description (e.g., "Sending OTPs, transaction alerts, and order confirmations to our mobile app customers").
is_otp	boolean	Optional	Flag indicating whether this sender ID will be used to send One-Time Passwords (OTPs) or verification codes. If set to `true`, `otp_url` is strictly required under NCA clearinghouse regulations.
otp_url	string	Conditional	The public website or application URL where OTPs sent with this sender ID are verified (e.g., `https://example.com/login`). Must start with `http://` or `https://` (maximum 2048 characters). Required if `is_otp` is true.

NCA Regulation Note: Telecommunication networks and the National Communications Authority (NCA) require any Sender ID used for dispatching OTPs or 2FA authentication codes to have a registered application URL. Messages containing OTP keywords dispatched via unregistered non-OTP sender IDs will be rejected upstream.

Request Body Examples

Regular Sender ID

{
  "sender_name": "MyBrand",
  "purpose": "Dispatching newsletters and customer alerts."
}

OTP Sender ID (NCA Compliant)

{
  "sender_name": "MyBrand",
  "purpose": "Dispatching login two-factor authentication codes.",
  "is_otp": true,
  "otp_url": "https://mybrand.com/verify-otp"
}

Server Responses

201 / 200 Success Response

{
  "status": "success",
  "code": "2000",
  "message": "Sender ID 'MyBrand' submitted to the SMS Gateway API! Awaiting network verification.",
  "data": {
    "id": 42,
    "sender_name": "MyBrand",
    "status": "pending",
    "is_approved": false,
    "is_otp": true,
    "otp_url": "https://mybrand.com/verify-otp",
    "purpose": "Dispatching login two-factor authentication codes."
  }
}

422 Error Response

{
  "status": "error",
  "code": "4022",
  "message": "Validation failed: otp_url is required when registering an OTP sender ID under NCA regulations."
}

GET Fetch Approved Sender IDs

Active Senders

Retrieve a verified list of all registered and approved Sender IDs belonging to your account. Perfect for dynamically populating sender dropdowns in plugins, webhooks, or third-party CRM systems.

GEThttps://veloquipsms.top/api/sender_ids Legacy: /api/sender_ids.php

Authentication Options

You can authenticate using either the Authorization Bearer header (recommended) or via a query parameter:

Header: Authorization: Bearer YOUR_API_KEY

Query: ?key=YOUR_API_KEY

Query Parameters

Parameter	Type	Status	Description
key	string	Optional	Your API key if not supplied via Authorization header.
status	string	Optional	Filter by status. Defaults to `approved`. Pass `all` to view all requests.

Success Response (200 OK)

JSON Response

{
  "status": "success",
  "code": "2000",
  "message": "Sender IDs retrieved successfully.",
  "count": 2,
  "approved_senders": [
    "MyBrand",
    "AlertNotify"
  ],
  "data": [
    {
      "id": 1,
      "sender_name": "MyBrand",
      "status": "approved",
      "is_otp": true,
      "otp_url": "https://mybrand.com/verify-otp",
      "created_at": "2026-05-11 04:01:45"
    },
    {
      "id": 2,
      "sender_name": "AlertNotify",
      "status": "approved",
      "is_otp": false,
      "otp_url": null,
      "created_at": "2026-05-08 13:14:52"
    }
  ]
}

POST Check Specific Sender ID Status

Verification

Check the telecommunication network registration and approval state of a single Sender ID name.

POSThttps://veloquipsms.top/api/sender_status Legacy: /api/sender_status.php

Request Body (JSON)

JSON Payload

{
  "sender_name": "MyBrand"
}

Success Response (200 OK)

JSON Response

{
  "status": "success",
  "code": "2000",
  "data": {
    "id": 1,
    "sender_name": "MyBrand",
    "status": "Approved",
    "is_approved": true
  }
}

POST Bulk Voice Call Broadcast

Interactive Voice

Broadcast pre-recorded audio voice phone calls to customer mobile numbers. Upload a new audio recording (MP3/WAV) or reuse an existing voice_id.

POSThttps://veloquipsms.top/api/send_voice Legacy: /api/send_voice.php

Multipart Form-Data / JSON Parameters

Field	Type	Status	Description
campaign	string	Required	Title for your bulk voice campaign.
recipient	array / string	Required	Array of recipient phone numbers (e.g. `["0241234567", "0201234567"]`).
file	file	Conditional	Audio file (.mp3, .wav, .m4a). Do NOT pass if reusing an existing `voice_id`.
voice_id	string	Conditional	Voice ID from a prior campaign. Do NOT pass if uploading a new `file`.
is_schedule	boolean	Optional	Set `true` to schedule for future broadcast. Defaults to `false`.

Implementation Sample (PHP cURL)

PHP Implementation

<?php
$url = "https://veloquipsms.top/api/send_voice?key=YOUR_API_KEY";

$audioFile = curl_file_create('audio/alert.mp3', 'audio/mpeg', 'alert.mp3');
$payload = [
    'campaign'  => 'Promotional Alert',
    'recipient' => ['0241234567', '0201234567'],
    'file'      => $audioFile
];

$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => $url,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $payload,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Accept: application/json"]
]);

$response = curl_exec($ch);
curl_close($ch);
print_r(json_decode($response, true));
?>

API Rate Limits & SLA Standard REST keys are provisioned with 100 requests per minute. Need higher throughput for enterprise webhook bursts? Contact support for dedicated IP whitelisting.

Ready to Integrate?

Create a free account or log in to generate secure API keys, manage sender IDs, and test live dispatches.