OTP SMS API Documentation

1. API Overview

The NinzaSMS API allows an application to submit OTP delivery requests. Your application authenticates with its API key, submits the required parameters and checks the returned JSON response.

2. Authentication

Send your API key in the HTTP Authorization header using the Bearer format.

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Replace YOUR_API_KEY with the API key associated with your NinzaSMS account. Keep the key on your server and never expose it in browser-side JavaScript or public repositories.

3. API Endpoint

Public endpoint configured in this documentation:

POST https://ninzasms.in.net/auth/api/send_sms.php

4. Request Parameters

The exact accepted number formats, OTP length, message template rules and route availability depend on the active backend implementation and account setup.

5. JSON Request Example

Example request body for the SMS route:

{
  "sender_id": 123,
  "numbers": "9876543210",
  "variables_values": "123456",
  "rout": "sms"
}

Replace the example user ID, mobile number and OTP with your own server-side values. The example OTP is for demonstration only.

cURL command

curl -X POST \
  "https://ninzasms.in.net/auth/api/send_sms.php" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sender_id": 123,
    "numbers": "9876543210",
    "variables_values": "123456",
    "rout": "sms"
  }'

6. PHP cURL Integration

Run this example from your backend PHP application. It sends a JSON request and checks the HTTP code and the API's status field.

<?php
$apiKey = 'YOUR_API_KEY';

/*
 * Confirm this endpoint matches your deployed backend.
 */
$apiUrl = 'https://ninzasms.in.net/auth/api/send_sms.php';

$payload = [
    'sender_id'        => 123,
    'numbers'          => '9876543210',
    'variables_values' => '123456',
    'rout'             => 'sms',
];

$ch = curl_init($apiUrl);

curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10,
    CURLOPT_TIMEOUT        => 30,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
        'Accept: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);

$responseBody = curl_exec($ch);
$curlError = curl_error($ch);
$httpCode = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);

curl_close($ch);

if ($responseBody === false) {
    error_log('NinzaSMS cURL error: ' . $curlError);
    exit('Unable to connect to the OTP service.');
}

$response = json_decode($responseBody, true);

if (!is_array($response)) {
    error_log('NinzaSMS returned a non-JSON response. HTTP: ' . $httpCode);
    exit('Invalid response received from the OTP service.');
}

if (
    $httpCode >= 200 &&
    $httpCode < 300 &&
    isset($response['status']) &&
    (int) $response['status'] === 1
) {
    echo 'API accepted the request: ';
    echo htmlspecialchars(
        (string) ($response['msg'] ?? 'Success'),
        ENT_QUOTES,
        'UTF-8'
    );
} else {
    $message = (string) (
        $response['msg'] ?? 'OTP request failed.'
    );

    echo 'Request failed: ';
    echo htmlspecialchars($message, ENT_QUOTES, 'UTF-8');
}
?>

This example checks the JSON status returned by the API. A success response means the API reported success; it does not independently verify handset delivery.

7. JSON Response Examples

Successful request

{
  "status": 1,
  "msg": "✅ OTP Sent Successfully",
  "balance": 4.6
}

Illustrative response. The balance value depends on the account and transaction.

WhatsApp route success

{
  "status": 1,
  "msg": "✅ OTP Sent via WhatsApp",
  "balance": 4.9
}

The supplied response helper uses a WhatsApp-specific success message when the route is waninza.

Invalid mobile number

{
  "status": 0,
  "msg": "❌ Invalid mobile number. Please provide a valid 10-digit number.",
  "balance_deducted": false,
  "otp_sent": false
}

Insufficient balance

{
  "status": 0,
  "msg": "❌ Insufficient balance. Please recharge your account."
}

Authentication error

{
  "status": 0,
  "msg": "Invalid API Key."
}

Gateway unavailable

{
  "status": 0,
  "msg": "⚠️ Your network issue, please try again."
}

Examples above reflect the supplied response_helper.php. Actual responses can include additional fields depending on the endpoint and execution path.

8. HTTP Status Codes and Errors

Your application should handle both HTTP errors and JSON responses gracefully. Do not assume that every failed request can safely be retried: a timeout may happen after a request was already processed.

9. Security and Responsible Use

• Keep API keys private and store them in server-side configuration.
• Use HTTPS for API requests.
• Validate mobile numbers and user input on your server.
• Apply rate limits and abuse prevention to OTP endpoints.
• Avoid logging API keys, OTP values or other sensitive information.
• Use OTP messaging only for authorized recipients and legitimate purposes.
• Follow applicable telecom, consent, sender registration and DLT requirements for your use case.

Start Your Integration

Use the request and response examples above as a starting point. Before deploying, test with your own account and verify the actual endpoint, route behavior, billing behavior and delivery reporting.