REQUESTING FOR PIN

post 
https://smsbox.devotek.africa/api/otp/v1/request

headers

Field Type Description
api-key string

Basic Authentication Username
api-scret string

Basic Authentication Password

Content-Type string

application/json (JSON REQUEST)
application/xml (XML REQUEST)

body

Field Type Description
app_id string

Application ID

receiver number

Mobile number in valid international number format with country code. With leading + sign. Example +22651423121

SAMPLE DATA

post 
https://smsbox.devotek.africa/api/otp/v1/request
{
    "app_id": 1,
    "receiver": "+22617261524"
}

SAMPLE SCRIPT

post 
https://smsbox.devotek.africa/api/otp/v1/request
const axios = require("axios");
const https = require("https");
const btoa = require("btoa");

const content_type = "application/json";
const api-key = "<api-key>";
const api-scret = "<api-scret>";

function pin_request() {
  axios
    .post(
      "https://smsbox.devotek.africa/api/otp/v1/request",
      {
        app_id: 1,
        receiver: "255701000000",
      },
      {
        headers: {
          "Content-Type": content_type,
          Authorization: "Basic " + btoa(api-key + ":" + api-scret),
        },
        httpsAgent: new https.Agent({
          rejectUnauthorized: false,
        }),
      }
    )
    .then((response) => console.log("success", response.data))
    .catch((error) => console.error(error));
}

pin_request();
<?php
$api-key='<api-key>';
$api-scret = '<api-scret>';

// The data to send to the API
$postData = array(
    'app_id' => '1',
    'receiver' => '255701000000',
);

$Url ='https://smsbox.devotek.africa/api/otp/v1/request';

// Setup cURL
$ch = curl_init($Url);
error_reporting(E_ALL);
ini_set('display_errors', 1);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt_array($ch, array(
    CURLOPT_POST => TRUE,
    CURLOPT_RETURNTRANSFER => TRUE,
    CURLOPT_HTTPHEADER => array(
        'Authorization:Basic ' . base64_encode("$api-key:$api-scret"),
        'Content-Type: application/json'

    ),
    CURLOPT_POSTFIELDS => json_encode($postData)
));

// Send the request
$response = curl_exec($ch);

// Check for errors
if($response === FALSE){
        echo $response;

    die(curl_error($ch));
}
var_dump($response);
?>
https://github.com/SMSBox/beem-otp-api-sample/tree/master/requestPin

SAMPLE RESPONSE

post 
https://smsbox.devotek.africa/api/otp/v1/request
HTTP/1.1 200 OK 
{
    "status": true,
    "code": 200,
    "message": "OTP sent Successfully",
    "data": "otppinid-20250501124201b69738eb23955c906daf",
  }
HTTP/1.1 400 Bad Request
 {
  "code": 111,
  "message": "Invalid Sender Id"
}
HTTP/1.1 400 Bad Request
{
   "code": 101,
   "message": "Failed to send SMS"
}

VERIFICATION OF PIN

post 
https://smsbox.devotek.africa/api/otp/v1/verify

headers

Field Type Description
api-key string

Basic Authentication Username
api-scret string

Basic Authentication Password

Content-Type string

application/json (JSON REQUEST)
application/xml (XML REQUEST)

body

Field Type Description
pinid string

Pin ID

pin number

OTP pin to verify

SAMPLE DATA

post 
https://smsbox.devotek.africa/api/otp/v1/verify
{
       pinid: "otppinid-20250501124201b69738eb23955c906daf",
       pin: "241663",
}

SAMPLE SCRIPT

post 
https://smsbox.devotek.africa/api/otp/v1/verify
const axios = require("axios");
const https = require("https");
const btoa = require("btoa");

const api-key = "<api-key>";
const api-scret = "<api-scret>";
const content_type = "application/json";

function pin_verify() {
  axios
    .post(
      "https://smsbox.devotek.africa/api/otp/v1/verify",
      {
        pinid: "otppinid-20250501124201b69738eb23955c906daf",
        pin: "241663",
      },
      {
        headers: {
          "Content-Type": content_type,
          Authorization: "Basic " + btoa(api-key + ":" + api-scret),
        },
        httpsAgent: new https.Agent({
          rejectUnauthorized: false,
        }),
      }
    )
    .then((response) => console.log("success", response))
    .catch((error) => console.error(error));
}

pin_verify();
<?php

$api-key='<api-key>';
$api-scret = '<api-scret>';

$postData = array(
    'pinid' => '7fa81447-4a14-4c2f-925b-78be40047c63',
    'pin' => '231663',
);

$Url ='https://smsbox.devotek.africa/api/otp/v1/verify';

// Setup cURL
$ch = curl_init($Url);
error_reporting(E_ALL);
ini_set('display_errors', 1);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt_array($ch, array(
    CURLOPT_POST => TRUE,
    CURLOPT_RETURNTRANSFER => TRUE,
    CURLOPT_HTTPHEADER => array(
        'Authorization:Basic ' . base64_encode("$api-key:$api-scret"),
        'Content-Type: application/json'
    ),
    CURLOPT_POSTFIELDS => json_encode($postData)
));

// Send the request
$response = curl_exec($ch);

// Check for errors
if($response === FALSE){
        echo $response;

    die(curl_error($ch));
}
var_dump($response);
https://github.com/SMSBox/beem-otp-api-sample/tree/master/verifyPin

SAMPLE RESPONSE

post 
https://smsbox.devotek.africa/api/otp/v1/verify
HTTP/1.1 200 OK 
{
    "status": true,
    "code": 200,
    "message": "Valid OTP",
    "data": 1,
  }
HTTP/1.1 400 Bad Request
 {
  "code": 111,
  "message": "Invalid Sender Id"
}
HTTP/1.1 403 Incorrect Pin
{
   "data": {
       "message": {
           "code": 114,
           "message": "Incorrect Pin"
       }
   }
}

ERROR CODES

Specific error codes may be displayed within parenthesis when send or receive operations fail. The most common of these error codes are specified below

post 
https://apisms.beem.africa/v1/send

Error codes

Name Description
100 SMS sent successfully
OTP Message has been submitted.
101 Failed to send SMS
Failed to send the OTP pin generated
102 Invalid phone number
Invalid receiver
103 Phone number missing
receiver parameter is missing
104 Application Id missing
Application id parameter is missing
106 Application not found
Application is not found
107 Application is inactive
Application status is inactive
108 No channel found
Channel is not set for the application
109 Placeholder not found
Template definition does not contain a placeholder
110 Username or Password missing
Credentials for sending OTP sms are missing
111 Pin missing
Pin parameter is missing
112 pinid missing
pinid parameter is missing
113 pinid not found
pinid is inactive/incorrect
114 Incorrect Pin
Pin sent is not correct
115 Pin TimeOut
Pin sent is expired
116 Attempts Exceeded
Pin attempts have exceeded
117 Valid Pin
Pin is correct
118 Duplicate Pin
Pin is used again
Generated with apidoc 0.17.7 - 2019-07-02T12:25:28.411Z