Welcome to TECHWAVE VERIFY SMS API

Our API makes sending and verifying SMS messages as easy as sending a smile. Let’s get started! 😊

Start by creating an account and generating your API encryption key. We offer four products — the first three are OTP-based services, while the fourth is for ordinary SMS communication.

Product	Type	Description	Registration Requirement
Test	OTP (Live)	Sends live SMS only to your registered number — ideal for testing and development.	Basic account
Team	OTP (Live)	Sends live SMS to anyone who has given consent. Consent can be automated for bulk users or manual for small teams.	Requires easy form of registration
Live	OTP (Live)	Can send SMS to anyone, but requires a higher level of registration and verification.	Requires full registration
Standard SMS	Non-OTP	Enables sending ordinary SMS messages that are not one-time passwords. This product is created separately from the OTP services.	Click here to contact sales

Send SMS Code

Authenticate using your API key in the Authorization header. Below is a sample request that demonstrates how to encrypt sensitive data before sending it to the API endpoint.

🧠 cURL Example (Universal)


curl -X POST https://techwavelinks.co.ke/sms/takeaction.php \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
  "classA": {
    "email": "example@domain.com",
    "project": "my_project"
  },
  "classB": "ENCRYPTED: {
      phone: +254700000000,
      code: A1B-2C3,
      hash: unique_hash_value,
      label: verification project,
      callback_url: https://yourwebsite.com/callback,
      fuzz: [random 30-character string]
  }"
}'

🛡️ Note: The classB field is fully AES-256 encrypted using your private API key. It contains the following parameters before encryption:

Field	Description
`phone`	The recipient phone number in international format (e.g., +2547XXXXXXX).
`code`	The verification code sent to the user (alphanumeric format supported).
`hash`	A unique hash or token generated by your system for verification tracking.
`label`	A human-readable label describing the purpose of the verification.
`callback_url`	Optional endpoint that receives delivery or verification status updates.
`fuzz`	A randomly generated 30-character string for uniqueness and tracking. It masks the encryption by making it unpredictable.

🐘 PHP Example


<?php
// ==== CONFIG ====
$endpoint = "https://techwavelinks.co.ke/sms/takeaction.php"; 
$key = "YOUR_API_ENCRYPTION_KEY"; // 🔑 Keep private and secure

// ==== Generate Random String ====
function randomString($length = 30) {
    $chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789!@#$%^&*()-_=+[]{};:,<.>/?';
    $str = '';
    $maxIndex = strlen($chars) - 1;
    for ($i = 0; $i < $length; $i++) {
        $str .= $chars[random_int(0, $maxIndex)];
    }
    return $str;
}

$random30 = randomString(30);

// ==== Data ====
$classA = [
    "email"   => "example@domain.com",
    "project" => "my_project"
];

$classB = [
    "phone"        => "+254700000000",
    "code"         => "A1B-2C3",
    "hash"         => "unique_hash_value",
    "label"        => "verification project",
    "callback_url" => "https://yourwebsite.com/callback",
    "fuzz"         => $random30
];

// ==== Encryption ====
function encryptData($data, $key) {
    $iv = random_bytes(16);
    $ciphertext = openssl_encrypt(json_encode($data), "AES-256-CBC", $key, 0, $iv);
    return base64_encode($iv . $ciphertext);
}

$encryptedB = encryptData($classB, $key);

// ==== Payload ====
$payload = [
    "classA" => $classA,
    "classB" => $encryptedB
];

// ==== Send via cURL ====
$ch = curl_init($endpoint);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
curl_close($ch);

echo "Server Response: $response\n";
?>

Team SMS Consent API

The Team SMS Consent API allows your app or website to request and log user consent before sending live SMS messages under a team project. This ensures compliance and consent verification for each recipient.

🧾 Request Overview

Endpoint: https://techwavelinks.co.ke/sms/takeconsent.php

Method: POST

Content-Type: application/json

Authorization: Bearer YOUR_API_KEY

📦 Example Request (cURL)


curl -X POST https://techwavelinks.co.ke/sms/takeconsent.php \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
  "classA": {
    "email": "example@domain.com",
    "project": "team_project"
  },
  "classB": "ENCRYPTED: {
      phone: +254700000000,
      type: consent,
      hash: unique_hash_value,
      device: android,
      label: consent verification,
      callback_url: https://yourwebsite.com/callback,
      fuzz: [random 30-character string]
  }"
}'

🛡️ Note: The classB field is fully AES-256 encrypted using your private API key. Below are the parameters included before encryption:

Field	Description
`phone`	Recipient phone number in international format (e.g., +2547XXXXXXX).
`type`	Specifies the action type. For consent requests, this value is `consent`.
`hash`	A unique identifier or hash for tracking the request.
`device`	Device type used by the user (e.g., android, ios, web).
`label`	A description for the consent request (e.g., “consent verification”).
`callback_url`	Optional webhook endpoint for receiving confirmation or updates.
`fuzz`	A randomly generated 30-character string for uniqueness and tracking. It masks the encryption by making it unpredictable.

🐘 PHP Example


<?php
// ==== CONFIG ====
$endpoint = "https://techwavelinks.co.ke/sms/takeconsent.php"; 
$key = "YOUR_API_ENCRYPTION_KEY"; // 🔑 Keep private and secure

// ==== UTILS ====
function randomString($length = 30) {
    $chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789!@#$%^&*()-_=+[]{};:,<.>/?';
    $str = '';
    $maxIndex = strlen($chars) - 1;
    for ($i = 0; $i < $length; $i++) {
        $str .= $chars[random_int(0, $maxIndex)];
    }
    return $str;
}

$random30 = randomString(30);

// ==== SAMPLE DATA ====
$classA = [
    "email"   => "example@domain.com",
    "project" => "team_project"
];

$classB = [
    "phone"        => "+254700000000",
    "type"         => "consent",
    "hash"         => "unique_hash_value",
    "device"       => "android",
    "label"        => "consent verification",
    "callback_url" => "https://yourwebsite.com/callback",
    "fuzz"         => $random30
];

// ==== ENCRYPT FUNCTION ====
function encryptData($data, $key) {
    $iv = random_bytes(16);
    $ciphertext = openssl_encrypt(json_encode($data), "AES-256-CBC", $key, 0, $iv);
    return base64_encode($iv . $ciphertext);
}

$encryptedB = encryptData($classB, $key);

// ==== PREPARE PAYLOAD ====
$payload = [
    "classA" => $classA,
    "classB" => $encryptedB
];

// ==== SEND USING CURL ====
$ch = curl_init($endpoint);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
curl_close($ch);

echo "Server Response: $response\n";
?>

Verify Consent API

Use this API to verify that a recipient has given consent for receiving team SMS messages. The API checks the SMS logs for a matching code sent to the phone number and validates that it is still within the allowed timeframe (e.g., 5 minutes).

🧾 Request Overview

Endpoint: https://techwavelinks.co.ke/sms/takeverification.php

Method: POST

Content-Type: application/json

Authorization: Bearer YOUR_API_KEY

📦 Example Request (cURL)


curl -X POST https://techwavelinks.co.ke/sms/takeverification.php \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
  "classA": {
    "email": "example@domain.com",
    "project": "team_project"
  },
  "classB": "ENCRYPTED: {
      phone: +254700000000,
      type: consent,
      code: 123456,
      device: android,
      label: consent verification,
      callback_url: https://yourwebsite.com/callback,
      fuzz: [random 30-character string]
  }"
}'

🛡️ Note: The classB field is fully AES-256 encrypted using your private API key. Below are the parameters included before encryption:

Field	Description
`phone`	Recipient phone number in international format (e.g., +254700000000).
`type`	Must be `verify_consent` to indicate consent verification.
`code`	The code that was sent to the phone to verify consent.
`device`	Device type used by the user (e.g., android, ios, web).
`label`	Description for the verification action (e.g., “consent verification”).
`callback_url`	Optional webhook endpoint for receiving confirmation or updates.
`fuzz`	A randomly generated 30-character string for uniqueness and tracking. It masks the encryption by making it unpredictable.

🐘 PHP Example


<?php
$endpoint = "https://techwavelinks.co.ke/sms/takeverification.php";
$key = "YOUR_API_ENCRYPTION_KEY"; 

function randomString($length = 30) {
    $chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789!@#$%^&*()-_=+[]{};:,<.>/?';
    $str = '';
    for ($i = 0; $i < $length; $i++) {
        $str .= $chars[random_int(0, strlen($chars) - 1)];
    }
    return $str;
}

$random30 = randomString(30);

$classA = [
    "email"   => "example@domain.com",
    "project" => "team_project"
];

$classB = [
    "phone"        => "+254700000000",
    "type"         => "verify_consent",
    "code"         => "123456",
    "device"       => "android",
    "label"        => "consent verification",
    "callback_url" => "https://yourwebsite.com/callback",
    "fuzz"         => $random30
];

function encryptData($data, $key) {
    $iv = random_bytes(16);
    $ciphertext = openssl_encrypt(json_encode($data), "AES-256-CBC", $key, 0, $iv);
    return base64_encode($iv . $ciphertext);
}

$encryptedB = encryptData($classB, $key);

$payload = [
    "classA" => $classA,
    "classB" => $encryptedB
];

$ch = curl_init($endpoint);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
curl_close($ch);

echo "Server Response: $response\n";
?>

Verify Sent SMS API

This API is used to verify that a sent SMS was delivered and logged correctly. It checks the phone number, code, and associated database ID. If the verification succeeds, the server confirms delivery.

🧾 Request Overview

Endpoint: https://techwavelinks.co.ke/sms/takesent.php

Method: POST

Content-Type: application/json

Authorization: Bearer YOUR_API_KEY

📦 Example Request (cURL)


curl -X POST https://techwavelinks.co.ke/sms/takesent.php \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
  "classA": {
    "email": "example@domain.com",
    "project": "team_project"
  },
  "classB": "ENCRYPTED: {
      phone: +254700000000,
      type: verify,
      code: 123456,
      device: android,
      label: sent verification,
      callback_url: https://yourwebsite.com/callback,
      fuzz: [random 30-character string],
      db_id: 34
  }"
}'

🛡️ Note: The classB field is fully AES-256 encrypted using your private API key. Before encryption, the fields are:

Field	Description
`phone`	Recipient phone number in international format.
`type`	Must be `verify` to indicate SMS verification.
`code`	The code that was sent to the recipient.
`device`	Device type used by the recipient (e.g., android, ios).
`label`	Description of the verification purpose (e.g., "sent verification").
`callback_url`	Optional endpoint to receive updates or confirmation.
`fuzz`	A randomly generated 30-character string for uniqueness and tracking. It masks the encryption by making it unpredictable.
`db_id`	The ID of the SMS record in the database for verification.

🐘 PHP Example


<?php
$endpoint = "https://techwavelinks.co.ke/sms/takesent.php";
$key = "YOUR_API_ENCRYPTION_KEY";

function randomString($length = 30) {
    $chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789!@#$%^&*()-_=+[]{};:,<.>/?';
    $str = '';
    for ($i = 0; $i < $length; $i++) {
        $str .= $chars[random_int(0, strlen($chars) - 1)];
    }
    return $str;
}

$random30 = randomString(30);

$classA = [
    "email" => "example@domain.com",
    "project" => "team_project"
];

$classB = [
    "phone" => "+254700000000",
    "type" => "verify",
    "code" => "123456",
    "device" => "android",
    "label" => "sent verification",
    "callback_url" => "https://yourwebsite.com/callback",
    "fuzz" => $random30,
    "db_id" => 34
];

function encryptData($data, $key) {
    $iv = random_bytes(16);
    $ciphertext = openssl_encrypt(json_encode($data), "AES-256-CBC", $key, 0, $iv);
    return base64_encode($iv . $ciphertext);
}

$encryptedB = encryptData($classB, $key);

$payload = [
    "classA" => $classA,
    "classB" => $encryptedB
];

$ch = curl_init($endpoint);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
curl_close($ch);

echo "Server Response: $response\n";
?>

📡 SMS Callback Notification API

Once an SMS is successfully sent, the system automatically sends a callback request to the client’s specified callback_url. This allows real-time confirmation that the SMS was delivered and logged correctly on the client’s end.

🧾 Callback Overview

Triggered by: System after SMS is sent

Method: POST

Content-Type: application/json

Delivery Guarantee: Retries up to 3 times if client server does not respond with 200 OK.

📦 Example Callback Payload

{
  "status": "sent",
  "timestamp": "2025-10-16T14:35:42Z",
  "db_id": 34,
  "phone": "+254700000000",
  "code": "123456",
  "type": "verify",
  "device": "android",
  "label": "sent verification",
  "fuzz": "3LkP9xZvQwHn2eTy7aD6uS1bR0pC4mX",
  "meta": {
      "project": "team_project",
      "sender": "techwavelinks"
  }
}

✅ Expected Response (Client)

{
  "received": true,
  "message": "Callback logged successfully"
}

🐘 PHP Example (Client Side Receiver)


<?php
// callback.php - Example endpoint to receive callback

header('Content-Type: application/json');

// Read JSON input
$input = file_get_contents('php://input');
$data = json_decode($input, true);

// Verify required fields
if (isset($data['status'], $data['db_id'], $data['phone'])) {
    // Example: Log callback into database or file
    file_put_contents('callback_log.txt', date('c') . " - " . json_encode($data) . PHP_EOL, FILE_APPEND);

    // Respond with success
    echo json_encode(["received" => true, "message" => "Callback logged successfully"]);
} else {
    // Respond with error
    http_response_code(400);
    echo json_encode(["received" => false, "message" => "Invalid callback data"]);
}
?>

🧠 Notes

status will always be sent for successful messages. Future updates may include delivered or failed.
Callbacks are sent immediately after successful SMS dispatch from the gateway.
The db_id and fuzz can be used to match the callback to your original request. A randomly generated 30-character string for uniqueness and tracking. It masks the encryption by making it unpredictable.

Error Codes

Below are the possible error codes returned by the API, categorized by type of request.

🔑 Authentication Errors

Code	Description	Action
401	Unauthorized – Invalid or missing API key.	Check your API key and ensure it is sent in the Authorization header.
403	Forbidden – API key does not have access to this endpoint.	Verify API key permissions or upgrade your account.

⚠️ Validation / Request Errors

Code	Description	Action
400	Bad Request – Invalid JSON or missing required fields.	Check the request payload and ensure all required parameters are provided.
422	Unprocessable Entity – Data validation failed.	Ensure the format and values of parameters match the API specification.

💻 Server / Internal Errors

Code	Description	Action
500	Internal Server Error – Something went wrong on the server.	Retry the request later. Contact support if the issue persists.
503	Service Unavailable – Server is temporarily overloaded or down for maintenance.	Try again after some time.

💡 Tip: Always handle errors gracefully in your app by checking the response code before processing data.

📚 Docs

Welcome to TECHWAVE VERIFY SMS API

Send SMS Code

🧠 cURL Example (Universal)

🐘 PHP Example

Team SMS Consent API

🧾 Request Overview

📦 Example Request (cURL)

🐘 PHP Example

Verify Consent API

🧾 Request Overview

📦 Example Request (cURL)

🐘 PHP Example

Verify Sent SMS API

🧾 Request Overview

📦 Example Request (cURL)

🐘 PHP Example

📡 SMS Callback Notification API

🧾 Callback Overview

📦 Example Callback Payload

✅ Expected Response (Client)

🐘 PHP Example (Client Side Receiver)

🧠 Notes

Error Codes

🔑 Authentication Errors

⚠️ Validation / Request Errors

💻 Server / Internal Errors