VOOZH about

URL: https://www.smsglobal.com/otp-api/


👁 Image

Introduction

Integrating with our OTP API is easy. When you use SMSGlobal’s REST API to integrate SMS capabilities into your application, you’ll save hundreds of hours compared to building OTP functionality from the ground up.

Plus, you’ll be partnering with a global leader in SMS with all of your application’s SMS needs covered by one provider offering expert support.


Overview of Features Scroll to Top ▲

  1. 👁 Check
    Customizable OTP message content with code placeholder - {*code*}
  2. 👁 Check
    Customizable code length - 4 to 10 digits
  3. 👁 Check
    Customizable expiry time - 60 - 600 seconds
  4. 👁 Check
    Customizable origin address (sender)
  5. 👁 Check
    Message Expiry time - set the time when the OTP code becomes invalid / expired
  6. 👁 Check
    Only one valid OTP (the latest one) at a time, per destination number per API key.
  7. 👁 Check
    Validate or cancel OTP requests
  8. 👁 Check
    Supports unicode and other languages

How to get started Scroll to Top ▲

The following example demonstrates how to start the verification process to send a verification code to the end-user.

To send an OTP Scroll to Top ▲

This can be used for sending OTP.


var payload = {
  origin: 'from number',
  message: '{*code*} is your SMSGlobal verification code.',
  destination: 'destination'
};
// {*code*} placeholder is mandatory and will be replaced by an auto generated numeric code.
smsglobal.otp.send(payload, function(error, response) {
  if (response) {
    console.log(response);
  }
  if (error) {
    console.log(error);
  }
});
Success response object
{
  statusCode: 200,
  status: 'OK',
  data: {
    requestId: '404372541683676561917558',
    destination: '61400000000',
    validUnitlTimestamp: '2020-11-18 17:08:14',
    createdTimestamp: '2020-11-18 16:58:14',
    lastEventTimestamp: '2020-11-18 16:58:14',
    status: 'Sent'
  }
}
Error response object in the case of validation error
{
  statusCode: 400,
  status: 'Bad Request',
  data: {
    errors: {
     message: {
      errors: [
       'Message template should contain a placeholder for code i.e. {*code*}.'
      ]
     }
    }
  }
}
<?php
 require_once __DIR__ . '/vendor/autoload.php';
 // get your REST API keys from MXT https://mxt.smsglobal.com/integrations
 \SMSGlobal\Credentials::set('YOUR_API_KEY', 'YOUR_SECRET_KEY');
 $otp = new \SMSGlobal\Resource\Otp();
 try {
    $response = $otp->send('DESTINATION_NUMBER', '{*code*} is your SMSGlobal verification code.');
    print_r($response);
 } catch (\Exception $e) {
    echo $e->getMessage();
 }
The following json response will be returned by the server:
{
    "requestId": "404372541683674336263499",
    "validUnitlTimestamp": "2020-11-18 16:24:51",
    "createdTimestamp": "2020-11-18 16:22:51",
    "lastEventTimestamp": "2020-11-18 16:22:51",
    "destination": "61400000000",
    "status": "Sent"
}
 
var client = new Client(new Credentials("SMSGLOBAL-API-KEY", "SMSGLOBAL-SECRET-KEY"));
var response = await client.OTP.OTPSend(new
 {
    message = "{*code*} is your SMSGlobal verification code.",
    destination = "DESTINATION-NUMBER",
});

The response object will contain OTP details such as request id, destination number such as:


{
 "requestId":"409261431691990777288109",
 "destination":"61450000000",
 "validUnitlTimestamp":"2021-02-18 11:39:07",
 "createdTimestamp":"2021-02-18 11:29:07",
 "lastEventTimestamp":"2021-02-18 11:29:08",
 "status":"Sent",
 "statuscode":200,
 "statusmessage":"OK"
}

To cancel an OTP request Scroll to Top ▲

The OTP request can be cancelled if it's not expired and verified yet. It can be done by either using requestId or destination number. The followings are examples of each method:


var id = 'otp-request-id'; // requestId received upon sending an OTP
 var promise = smsglobal.otp.cancelByRequestId(id)
 promise.then((response) => {
  console.log(response)
 }).catch((err) => {
  console.log(error)
 });
var destination = 'destination-number';
var promise = smsglobal.otp.cancelByDestination(id)
promise.then((response) => {
  console.log(response)
}).catch((err) => {
  console.log(error)
});
Success response object
{
  statusCode: 200,
  status: 'OK',
  data: {
    requestId: '404372541683676561917558',
    destination: '61400000000',
    validUnitlTimestamp: '2020-11-18 17:08:14',
    createdTimestamp: '2020-11-18 16:58:14',
    lastEventTimestamp: '2020-11-18 16:58:14',
    status: 'Cancelled'
  }
}
require_once __DIR__ . '/vendor/autoload.php';
 // get your REST API keys from MXT https://mxt.smsglobal.com/integrations
 \SMSGlobal\Credentials::set('YOUR_API_KEY', 'YOUR_SECRET_KEY');
 $otp = new \SMSGlobal\Resource\Otp();
 try {
    $response = $otp->cancelByRequestId('request Id');
    print_r($response);
 } catch (\Exception $e) {
    echo $e->getMessage();
 }
require_once __DIR__ . '/vendor/autoload.php';
// get your REST API keys from MXT https://mxt.smsglobal.com/integrations
\SMSGlobal\Credentials::set('YOUR_API_KEY', 'YOUR_SECRET_KEY');
$otp = new \SMSGlobal\Resource\Otp();
try {
    $response = $otp->cancelByDestination('destination number');
    print_r($response);
} catch (\Exception $e) {
    echo $e->getMessage();
}

The following json response will be returned by the server if cancellation is successfull:


{
    "requestId": "404372541683674336263499",
    "validUnitlTimestamp": "2020-11-18 16:24:51",
    "createdTimestamp": "2020-11-18 16:22:51",
    "lastEventTimestamp": "2020-11-18 16:22:51",
    "destination": "61400000000",
    "status": "Cancelled"
}
 
var client = new Client(new Credentials("SMSGLOBAL-API-KEY", "SMSGLOBAL-SECRET-KEY"));
 string requestid = "REQUEST-ID";
 var response = await client.OTP.OTPCancelRequest(requestid);
var client = new Client(new Credentials("SMSGLOBAL-API-KEY", "SMSGLOBAL-SECRET-KEY"));
string destination = "DESTINATION-NUMBER";
var response = await client.OTP.OTPCancelDestination(destination);

The response object will contain OTP details such as request id, destination number such as:


{
 "requestId":"409261431691990777288109",
 "destination":"61450000000",
 "validUnitlTimestamp":"2021-02-18 11:39:07",
 "createdTimestamp":"2021-02-18 11:29:07",
 "lastEventTimestamp":"2021-02-18 11:29:08",
 "status":"Cancelled ",
 "statuscode":200,
 "statusmessage":"OK"
 }

To verify an OTP code entered by your user Scroll to Top ▲

The OTP code entered by your user can be verified by either using requestId or destination number. The followings are examples of each method:


var id = 'otp-request-id'; // requestId received upon sending an OTP
var code = 'otp-code'; // input code entered by your user
smsglobal.otp.verifyByRequestId(id, code, function(error, response) {
  if (response) {
    console.log(response);
  }
  if (error) {
    console.log(error);
  }
});
var destination = 'destination-number';
var code = 'otp-code'; // input code entered by your user
smsglobal.otp.verifyByDestination(id, code, function(error, response) {
  if (response) {
    console.log(response);
  }
  if (error) {
    console.log(error);
  }
});
Success response object
{
  statusCode: 200,
  status: 'OK',
  data: {
    requestId: '404372541683676561917558',
    destination: '61400000000',
    validUnitlTimestamp: '2020-11-18 17:08:14',
    createdTimestamp: '2020-11-18 16:58:14',
    lastEventTimestamp: '2020-11-18 16:58:14',
    status: 'Verified'
  }
}
<?php
 require_once __DIR__ . '/vendor/autoload.php';
 // get your REST API keys from MXT https://mxt.smsglobal.com/integrations
 \SMSGlobal\Credentials::set('YOUR_API_KEY', 'YOUR_SECRET_KEY');
 $otp = new \SMSGlobal\Resource\Otp();
 try {
    $response = $otp->verifyByRequestId('request Id', 'OTP code enterted by your user.');
    print_r($response);
 } catch (\Exception $e) {
    echo $e->getMessage();
 }
<?php
require_once __DIR__ . '/vendor/autoload.php';
// get your REST API keys from MXT https://mxt.smsglobal.com/integrations
\SMSGlobal\Credentials::set('YOUR_API_KEY', 'YOUR_SECRET_KEY');
$otp = new \SMSGlobal\Resource\Otp();
try {
    $response = $otp->verifyByDestination('destination number', 'OTP code enterted by your user.');
    print_r($response);
} catch (\Exception $e) {
    echo $e->getMessage();
}

The following json response will be returned by the server if verification is successfull:


{
    "requestId": "404372541683674336263499",
    "validUnitlTimestamp": "2020-11-18 16:24:51",
    "createdTimestamp": "2020-11-18 16:22:51",
    "lastEventTimestamp": "2020-11-18 16:22:51",
    "destination": "61400000000",
    "status": "Verified"
}
 
var client = new Client(new Credentials("SMSGLOBAL-API-KEY", "SMSGLOBAL-SECRET-KEY"));
string requestid = "REQUEST-ID";
string code = "OTP-CODE";
var response = await client.OTP.OTPValidateRequest(requestid, new
{
    code = code,
});
var client = new Client(new Credentials("SMSGLOBAL-API-KEY", "SMSGLOBAL-SECRET-KEY"));
string destinationid = "DESTINATION-NUMBER";
string code = "OTP-CODE";
var response = await client.OTP.OTPValidateDestination(destinationid, new
{
    code = code,
});

The response object will contain OTP details such as request id, destination number such as:


{
 "requestId":"409261431691990777288109",
 "destination":"61450000000",
 "validUnitlTimestamp":"2021-02-18 11:39:07",
 "createdTimestamp":"2021-02-18 11:29:07",
 "lastEventTimestamp":"2021-02-18 11:29:08",
 "status":"Verified",
 "statuscode":200,
 "statusmessage":"OK"
}

REST API Endpoints Scroll to Top ▲

Authentication

The REST API uses an authentication scheme based on this OAuth 2 specification . All requests to resources (excluding the schema pages) must be accompanied by a correct Authorization header as per this specification. The header looks like this:

 Authorization: MAC id="your API key", ts="1325376000", nonce="random-string", mac="base64-encoded-hash" 


  • OTP
    /v2/otp
    • POST /v2/otp beta since v2

      Documentation

      Send an OTP message to a given destination number

      Parameters

      ParameterTypeRequired?FormatDescription
      messagestringtrueRequest identifier
      lengthintegerfalseLength of the code between 4-10 digits. The default is 6.
      codeExpiryintegerfalseNo. of seconds after an OtpApi should expire. It should be 60 seconds or greater. Default is 10 minutes
      originstringfalseWhere the SMS appears to come from. 3-11 characters A-Za-z0-9 if alphanumeric; 3-15 digits if numeric
      destinationstringtrueDestination mobile number. 3-15 digits
      messageExpiryDateTimedatetimefalseyyyy-MM-dd HH:mm:ssThe datetime in UTC at message will expire.

      Return

      ParameterTypeVersionsDescription
      requestIdstring>=v2Message template. E.g. {*code*} is your security code. A message is only valid if it contains the code placeholder i.e. {*code*}.
      destinationstring>=v2Destination mobile number. 4-15 digits
      validUnitlTimestampDateTime>=v2Returns validUnitlTimestamp in associated user's account timezone
      createdTimestampDateTime>=v2Returns createdTimestmap in associated user's account timezone
      lastEventTimestampDateTime>=v2Returns lastEventTimestamp in associated user's account timezone
      statusstring>=v2Returns human readable status

      Status Codes

      Status CodeDescription
      200
      • Returned when successful
      400
      • Returned when input validation failed
      402
      • Returned when account is out of credits
      403
      • Returned when the user is not authorized
      405
      • Method not allowed
    /v2/otp/requestid/{id}/cancel
    • POST /v2/otp/requestid/{id}/cancel beta since v2

      Documentation

      Cancel an OTP request identified by request id.

      Requirements

      NameRequirementTypeDescription
      idstringRequest Id

      Return

      ParameterTypeVersionsDescription
      requestIdstring>=v2Request identifier
      destinationstring>=v2Destination mobile number. 4-15 digits
      validUnitlTimestampDateTime>=v2Returns validUnitlTimestamp in associated user's account timezone
      createdTimestampDateTime>=v2Returns createdTimestmap in associated user's account timezone
      lastEventTimestampDateTime>=v2Returns lastEventTimestamp in associated user's account timezone
      statusstring>=v2Returns human readable status

      Status Codes

      Status CodeDescription
      200
      • Returned when successful
      403
      • Returned when the user is not authorized
      404
      • Returned when the OTP is not found
      405
      • Method not allowed
    /v2/otp/requestid/{id}/validate
    • POST /v2/otp/requestid/{id}/validate beta since v2

      Documentation

      Validate an OTP code against the OTP request identified by request id.

      Requirements

      NameRequirementTypeDescription
      idstringRequest Id

      Parameters

      ParameterTypeRequired?FormatDescription
      codestringtrueThe OtpApi verification code entered by your user.

      Return

      ParameterTypeVersionsDescription
      requestIdstring>=v2Request identifier
      destinationstring>=v2Destination mobile number. 4-15 digits
      validUnitlTimestampDateTime>=v2Returns validUnitlTimestamp in associated user's account timezone
      createdTimestampDateTime>=v2Returns createdTimestmap in associated user's account timezone
      lastEventTimestampDateTime>=v2Returns lastEventTimestamp in associated user's account timezone
      statusstring>=v2Returns human readable status

      Status Codes

      Status CodeDescription
      200
      • Returned when successful
      400
      • Returned when input validation failed
      403
      • Returned when the user is not authorized
      404
      • Returned when the OTP is not found
      405
      • Method not allowed
    /v2/otp/{msisdn}/cancel
    • POST /v2/otp/{msisdn}/cancel beta since v2

      Documentation

      Cancel an OTP request identified by destination number.

      Requirements

      NameRequirementTypeDescription
      msisdnstringDestination number

      Return

      ParameterTypeVersionsDescription
      requestIdstring>=v2Request identifier
      destinationstring>=v2Destination mobile number. 4-15 digits
      validUnitlTimestampDateTime>=v2Returns validUnitlTimestamp in associated user's account timezone
      createdTimestampDateTime>=v2Returns createdTimestmap in associated user's account timezone
      lastEventTimestampDateTime>=v2Returns lastEventTimestamp in associated user's account timezone
      statusstring>=v2Returns human readable status

      Status Codes

      Status CodeDescription
      200
      • Returned when successful
      403
      • Returned when the user is not authorized
      404
      • Returned when the OTP is not found
      405
      • Method not allowed
    /v2/otp/{msisdn}/validate
    • POST /v2/otp/{msisdn}/validate beta since v2

      Documentation

      Validate an OTP code against the OTP request identified by destination number.

      Requirements

      NameRequirementTypeDescription
      msisdnstringDestination number

      Parameters

      ParameterTypeRequired?FormatDescription
      codestringtrueThe OtpApi verification code entered by your user.

      Return

      ParameterTypeVersionsDescription
      requestIdstring>=v2Request identifier
      destinationstring>=v2Destination mobile number. 4-15 digits
      validUnitlTimestampDateTime>=v2Returns validUnitlTimestamp in associated user's account timezone
      createdTimestampDateTime>=v2Returns createdTimestmap in associated user's account timezone
      lastEventTimestampDateTime>=v2Returns lastEventTimestamp in associated user's account timezone
      statusstring>=v2Returns human readable status

      Status Codes

      Status CodeDescription
      200
      • Returned when successful
      400
      • Returned when input validation failed
      403
      • Returned when the user is not authorized
      404
      • Returned when the OTP is not found
      405
      • Method not allowed
Loading Form