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.
The following example demonstrates how to start the verification process to send a verification code to the end-user.
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); } });
{ 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' } }
{ 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(); }
{ "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" }
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) });
{ 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" }
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); } });
{ 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" }
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"
Send an OTP message to a given destination number
Parameter | Type | Required? | Format | Description |
---|---|---|---|---|
message | string | true | Request identifier | |
length | integer | false | Length of the code between 4-10 digits. The default is 6. | |
codeExpiry | integer | false | No. of seconds after an OtpApi should expire. It should be 60 seconds or greater. Default is 10 minutes | |
origin | string | false | Where the SMS appears to come from. 3-11 characters A-Za-z0-9 if alphanumeric; 3-15 digits if numeric | |
destination | string | true | Destination mobile number. 3-15 digits | |
messageExpiryDateTime | datetime | false | yyyy-MM-dd HH:mm:ss | The datetime in UTC at message will expire. |
Parameter | Type | Versions | Description |
---|---|---|---|
requestId | string | >=v2 | Message template. E.g. {*code*} is your security code. A message is only valid if it contains the code placeholder i.e. {*code*}. |
destination | string | >=v2 | Destination mobile number. 4-15 digits |
validUnitlTimestamp | DateTime | >=v2 | Returns validUnitlTimestamp in associated user's account timezone |
createdTimestamp | DateTime | >=v2 | Returns createdTimestmap in associated user's account timezone |
lastEventTimestamp | DateTime | >=v2 | Returns lastEventTimestamp in associated user's account timezone |
status | string | >=v2 | Returns human readable status |
Status Code | Description |
---|---|
200 |
|
400 |
|
402 |
|
403 |
|
405 |
|
Cancel an OTP request identified by request id.
Name | Requirement | Type | Description |
---|---|---|---|
id | string | Request Id |
Parameter | Type | Versions | Description |
---|---|---|---|
requestId | string | >=v2 | Request identifier |
destination | string | >=v2 | Destination mobile number. 4-15 digits |
validUnitlTimestamp | DateTime | >=v2 | Returns validUnitlTimestamp in associated user's account timezone |
createdTimestamp | DateTime | >=v2 | Returns createdTimestmap in associated user's account timezone |
lastEventTimestamp | DateTime | >=v2 | Returns lastEventTimestamp in associated user's account timezone |
status | string | >=v2 | Returns human readable status |
Status Code | Description |
---|---|
200 |
|
403 |
|
404 |
|
405 |
|
Validate an OTP code against the OTP request identified by request id.
Name | Requirement | Type | Description |
---|---|---|---|
id | string | Request Id |
Parameter | Type | Required? | Format | Description |
---|---|---|---|---|
code | string | true | The OtpApi verification code entered by your user. |
Parameter | Type | Versions | Description |
---|---|---|---|
requestId | string | >=v2 | Request identifier |
destination | string | >=v2 | Destination mobile number. 4-15 digits |
validUnitlTimestamp | DateTime | >=v2 | Returns validUnitlTimestamp in associated user's account timezone |
createdTimestamp | DateTime | >=v2 | Returns createdTimestmap in associated user's account timezone |
lastEventTimestamp | DateTime | >=v2 | Returns lastEventTimestamp in associated user's account timezone |
status | string | >=v2 | Returns human readable status |
Status Code | Description |
---|---|
200 |
|
400 |
|
403 |
|
404 |
|
405 |
|
Cancel an OTP request identified by destination number.
Name | Requirement | Type | Description |
---|---|---|---|
msisdn | string | Destination number |
Parameter | Type | Versions | Description |
---|---|---|---|
requestId | string | >=v2 | Request identifier |
destination | string | >=v2 | Destination mobile number. 4-15 digits |
validUnitlTimestamp | DateTime | >=v2 | Returns validUnitlTimestamp in associated user's account timezone |
createdTimestamp | DateTime | >=v2 | Returns createdTimestmap in associated user's account timezone |
lastEventTimestamp | DateTime | >=v2 | Returns lastEventTimestamp in associated user's account timezone |
status | string | >=v2 | Returns human readable status |
Status Code | Description |
---|---|
200 |
|
403 |
|
404 |
|
405 |
|
Validate an OTP code against the OTP request identified by destination number.
Name | Requirement | Type | Description |
---|---|---|---|
msisdn | string | Destination number |
Parameter | Type | Required? | Format | Description |
---|---|---|---|---|
code | string | true | The OtpApi verification code entered by your user. |
Parameter | Type | Versions | Description |
---|---|---|---|
requestId | string | >=v2 | Request identifier |
destination | string | >=v2 | Destination mobile number. 4-15 digits |
validUnitlTimestamp | DateTime | >=v2 | Returns validUnitlTimestamp in associated user's account timezone |
createdTimestamp | DateTime | >=v2 | Returns createdTimestmap in associated user's account timezone |
lastEventTimestamp | DateTime | >=v2 | Returns lastEventTimestamp in associated user's account timezone |
status | string | >=v2 | Returns human readable status |
Status Code | Description |
---|---|
200 |
|
400 |
|
403 |
|
404 |
|
405 |
|