The Danal Phone Verification Developer Hub

Welcome to the Danal Phone Verification developer hub. You'll find comprehensive guides and documentation to help you start working with Danal Phone Verification as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    
Suggest Edits

Verify a Phone Number

 
gethttps://api.phoneverification.io/api/v1/verifyPhoneNumber/phoneNumber

Start Building

Check out the sample code to get started

Request Parameters

Parameter
Possible Values
Description

phoneNumber
Required Path Parameter

"%2B14082323300"

"%2B35319060988"

URLEncoded E.164 formatted phone number, provided by your user

More on E.164

authToken
Required

MDBDQTQ0MzAwMDk5OnA5
ZDdmVVRHSEpkR2UydWY6a
DYyY3RrU0hKR0RadjU5ZWtv
Wnd1UmlGVHc9PQ

Encrypted credentials to authenticate access to APIs. Please refer to the "API Authentication" section

fallback

0

1 (default)

Choose fallback method when the phone is on an unsupported mobile operator or Wi-Fi.

  • 0 - No fallback selected. Use this if you have another SMS provider

  • 1 - One time pin-code delivered via SMS. This is the default

Note: If you plan to use an alternate SMS provider, please set this value to 0. Otherwise your users will receive an SMS

appName

"company name"
"application name"

The name of the company or App you are using Verify for. This will be added in front of the SMS message. For example: "App Name: 366456 is your pin code".

Note: Keep this blank if you chose 0 for fallback. This value will be ignored of fallback is not chosen.

smsMessage

"If you didn't request the code please ignore this request or go to yourapp.com/help for assistance."

Message to be sent to the user with SMS fallback. This will be added to the SMS message after the PIN code.

The final message will look like

App Name: 366456 is your pin code. If you didn't request the code please ignore this message or go to yourapp.com/help for assistance.

Note: Keep this blank if you chose 0 for fallback. This value will be ignored of fallback is not chosen.

Response Values

Parameter
Possible Values
Description

status

0
1
2
-1

Status of the request

0 - Verification failed
1 - Verification succeeded
2 - Switch to fallback verification method (chosen in the fallback parameter)
-1 - Error

statusMessage

"Verification succeeded"
"Verification failed"
"Switch to fallback"
"Error try again"

Descriptive text to let you know what happened

Follow Redirects

Danal APIs utilize HTTP 302 redirects to accomplish the phone verification process. Please follow the outlined guidelines to ensure proper execution of the API.

Whether you build an iOS or Android app, please ensure that you follow redirects from your code. Depending on the platform of your choice configure your code to automatically follow any redirect responses sent back from the Danal API. See example code above.

For mobile web applications, it's important to use JSONP when calling the Phone Verification API. This ensures that the mobile browsers follow the redirect URLs. More on JSONP: https://www.w3schools.com/js/js_json_jsonp.asp

// See full sample code at https://github.com/danal-pvs/phone-verification-samples/blob/master/client/JavaScript/main.js

function verifyMobileNumber() 
{
  getJsonp(apiURLs.verifyPhoneNumber, {
    appName: "My Application",
    fallback: "1",
    smsMessage: "Please visit app.com for assistance."
  }, function (err, data) {
    if (err) {
      hideSpinner();
      console.error('Failed to verify Mobile Number: ' + err);
    } else {
      console.log('SUCCESS: ' + JSON.stringify(data));
      handleDanalResponse(data);
    }
  });
}
// See full sample code at https://github.com/danal-pvs/phone-verification-samples/blob/master/client/Android/app/src/main/java/com/danalinc/samples/phoneverification/VerifyPhone.java

private void verifyPhone() {
  Map<String, String> parameters = new HashMap<>();
  parameters.put("appName", "My Application");
  parameters.put("fallback", "1");
  parameters.put("smsMessage", "Please visit app.com for assistance.");

  String url = (String) apiURLs.get("verifyPhoneNumber");
  HttpHelper httpHelper = HttpHelper.builder()
    .parameters(parameters)
    .listener(this)
    .build();
  httpHelper.execute(url, "verifyPhoneNumber");
}
// See full sample code at https://github.com/danal-pvs/phone-verification-samples/tree/master/client/iOS/PhoneVerification-iOS

url = URL(string: "https://api.phoneverification.io/verifyPhoneNumber/"+phoneNumber)!
request = URLRequest(url: url)
request.httpMethod = "POST"
        
task = URLSession.shared.dataTask(with: request) { data, response, error in

    do {
        let json = try JSONSerialization.jsonObject(with: data, options: .allowFragments) as! [String:Any]
                
        let statusCode = json["status"] as! Int
            
        if(statusCode == 1) {
            // Phone verification successfull
        } else if(statusCode == 0) {
            // Phone verification failed
        } else if(statusCode == 2) {
            // Switch to fallback
        } else if(statusCode == -1) {
            // Phone verification error
        }
    } catch let error as NSError {
       // API call error
    }
    
}
A binary file was returned

You couldn't be authenticated

{
  status:1,
  statusMessage: "Verification Succeeded"
}
 
Suggest Edits

Fallback: Verify SMS Code

 
gethttps://api.phoneverification.io/api/v1/verifySMSCode/phoneNumber

Start Building

Check out the sample code to get started.

Request Parameters

Request Parameter
Possible Values
Description

phoneNumber
Required Path Parameter

"%2B14082323300"

"%2B35319060988"

URLEncoded E.164 formatted phone number, provided by your user

More on E.164

authToken
Required

MDBDQTQ0MzAwMDk5OnA5
ZDdmVVRHSEpkR2UydWY6a
DYyY3RrU0hKR0RadjU5ZWtv
Wnd1UmlGVHc9PQ

Encrypted credentials to authenticate access to APIs. Please refer to the "API Authentication" section

code
Required

234353

6 digit pin-code provided by the user

Response Values

Response Parameter
Possible Values
Description

status

0
1
-1

Status of the request

0 - Validation failed
1 - Validation succeeded
-1 - Error

statusMessage

"Validation Succeeded"
"Validation Failed"
"Error Try Again"

Descriptive text to let you know what happened

// See full sample code at https://github.com/danal-pvs/phone-verification-samples/blob/master/client/JavaScript/main.js

function verifySMSCode() {
  showSpinner();
  var pin = $('#pinInput').val().trim();
  getJsonp(apiURLs.verifySMSCode, {
    code: pin
  }, function (err, data) {
    if (err) {
      hideSpinner();
      console.error('Failed to verify SMS Code: ' + err);
    } else {
      console.log('SUCCESS: ' + JSON.stringify(data));
      handleDanalResponse(data);
    }
  });
}
// See full sample code at https://github.com/danal-pvs/phone-verification-samples/blob/master/client/Android/app/src/main/java/com/danalinc/samples/phoneverification/VerifyPhone.java
private void verifySMSCode() {
  setProgressVisibility(true);
  EditText pinView = findViewById(R.id.pinText);
  String pin = pinView.getText().toString().trim();
  if (pin.length() > 10) {
    //pin is currently length of 6, but here's some buffer in case that ever changes
    showAlert("Please enter a valid PIN");
    return;
  }

  Map<String, String> parameters = new HashMap<>();
  parameters.put("code", pin);
  String url = (String) apiURLs.get("verifySMSCode");

  HttpHelper httpHelper = HttpHelper.builder()
    .parameters(parameters)
    .listener(this)
    .build();
  httpHelper.execute(url, "verifySMSCode");
}
// See full sample code at https://github.com/danal-pvs/phone-verification-samples/tree/master/client/iOS/PhoneVerification-iOS

url = URL(string: "https://api.phoneverification.io/verifySMSCode/"+phoneNumber)!
request = URLRequest(url: url)
request.httpMethod = "POST"
        
task = URLSession.shared.dataTask(with: request) { data, response, error in

    do {
        let json = try JSONSerialization.jsonObject(with: data, options: .allowFragments) as! [String:Any]
                
        let statusCode = json["status"] as! Int
            
        if(statusCode == 1) {
            // SMS validation successfull
        } else if(statusCode == 0) {
            // SMS validation failed
        } else if(statusCode == -1) {
            // SMS validation error
        } 
    } catch let error as NSError {
       // API call error
    }
    
}
A binary file was returned

You couldn't be authenticated

{
  status:1,
  statusMessage: "Validation Succeeded"
}
 
Suggest Edits

Fallback: Resend Code

 
gethttps://api.phoneverification.io/api/v1/resendCode/phoneNumber

Start Building

Check out the sample code to get started.

Request Parameters

Parameter
Possible Values
Description

phoneNumber
Required Path Parameter

"%2B14082323300"

"%2B35319060988"

URLEncoded E.164 formatted phone number, provided by your user

More on E.164

authToken
Required

MDBDQTQ0MzAwMDk5OnA5
ZDdmVVRHSEpkR2UydWY6a
DYyY3RrU0hKR0RadjU5ZWtv
Wnd1UmlGVHc9PQ

Encrypted credentials to authenticate access to APIs. Please refer to the "API Authentication" section

Response Values

Parameter
Possible Values
Description

status

0
1

Status of the request
0 - resend failed
1 - resend succeeded

statusMessage

"Success"
"Failed"

Descriptive text for the status

// See full sample code at https://github.com/danal-pvs/phone-verification-samples/blob/master/client/JavaScript/main.js


function resendCode() {
  showSpinner();
  getJsonp(apiURLs.resendCode, {}, function (err, data) {
    hideSpinner();
    if (err) {
      console.error('Failed to resend SMS Code: ' + err);
    } else {
      console.log('SUCCESS: ' + JSON.stringify(data));
      var status = data.status;
      if (status == DanalResponseStatus.SUCCESS) {
        setMessage('Resent SMS Code');
      } else {
        setMessage('Failed to resend SMS Code: ' + err);
      }
    }
  });
}
// See full sample code at https://github.com/danal-pvs/phone-verification-samples/blob/master/client/Android/app/src/main/java/com/danalinc/samples/phoneverification/VerifyPhone.java

private void resendCode() {
  setProgressVisibility(true);
  String url = (String) apiURLs.get("resendCode");
  HttpHelper httpHelper = HttpHelper.builder()
    .parameters(new HashMap<String, String>())
    .listener(this)
    .build();
  httpHelper.execute(url, "resendCode");
}
// See full sample code at https://github.com/danal-pvs/phone-verification-samples/tree/master/client/iOS/PhoneVerification-iOS

url = URL(string: "https://api.phoneverification.io/resendCode/"+phoneNumber)!
request = URLRequest(url: url)
request.httpMethod = "POST"
        
task = URLSession.shared.dataTask(with: request) { data, response, error in

    do {
        let json = try JSONSerialization.jsonObject(with: data, options: .allowFragments) as! [String:Any]
                
        let statusCode = json["status"] as! Int
            
        if(statusCode == 1) {
            // SMS code resend successfull
        } else if(statusCode == 0) {
            // SMS code resend failed
        } 
    } catch let error as NSError {
       // API call error
    }
    
}
A binary file was returned

You couldn't be authenticated

{
  status:1,
  statusMessage: "Resend Succeeded"
}
 
Suggest Edits

API Authentication

 

All the APIs provided by Danal's Phone Verification service require an "Authentication Token" as a parameter on the API call.

For security, this token should be generated on your server and fetched by the app before making the API calls. Theoretically, these can be generated on the mobile app but that would require storing the app credentials (App ID and Encryption key) on the mobile device. This poses a serious security risk. An attacker could decompile the application, extract your credentials and use your credentials for their app.

Here is the recommended flow:

Auth Token Generation Flow

Auth Token Generation Flow

  1. Once the user enters the phone number and taps the "Verify" button on your screen, initiate the API call to your server to fetch the token
  2. Your server uses the app credentials (App ID and Encryption key provided by Danal) to generate the unique auth token for the user
  3. Use the auth token in your API calls to verify the phone number
  4. Receive response and take appropriate next steps in your app

Best Time to Get Token
Call your server to get the auth token only when the user has entered the phone number and initiated the verification process by clicking the button. Since the tokens are short-lived, you want to generate them only when your app is sure that the user has initiated the verification process.

Start Building

Check out the sample code to get started

Auth Token Detailed Breakdown

Generating the auth token requires using both the App ID and Encryption key provided by Danal. The token is a base64 encoded string comprising of three components, all separated by a colon ":"

Your App ID:Salt(base64 encoded):AES encrypted payload(base64 encoded)

Your App ID

Once you request access to use these APIs, we will create and provide a unique ID to you and assign it to your app. This will recognize your app within the Danal system.

Salt

16 bytes of random data used as an additional input to the cipher algorithm to perform the encryption. This is the same salt that will be used within the AES encryption.

AES Encrypted Payload

Current timestamp in yyyyMMddHHmmss format and a nonce value (5 digit random value) encrypted using an AES 128 bit key, Salt and AES/CTR/NoPadding algorithm. The Encryption Key will be provided by Danal along with the App ID.

 
Suggest Edits

Quick Start - Sample Code

 

Needs App Credentials

You will need to get app credentials (App ID and encryption keys) to use these APIs. Please contact us here to request these credentials.

Client App Code

You can use one of our client sample code to try the API with the complete verification flow. Simply point the code to your server for generating the auth token (with your app credentials) and perform phone verifications on the mobile client

Server Code

You can use one of our server sample code to deploy on your server to generate auth tokens. In these examples, our code generates the full URL the client will need to make the API call. This makes the process easy on the client.

Need More Help

 
Suggest Edits

Getting API Access

 

You will need to get app credentials (App ID and encryption keys) to use these APIs. Contact us here to request your credentials.

The form requests basic information about you and your company in order to set up the application. Please make sure you provide details of your application.

App Credentials

After submitting the "Request Access" form you will receive an email from the Danal team with your credentials. These include:

  1. App ID - Application identifier for your app
  2. Encryption Key - Unique encryption key for you to encrypt the authorization token when making API calls.
    Note: Please refer to the API Authentication section on how to use the App ID and Encryption Key.

Limits

The basic app credential provides you with 100 free transactions to help you during your build and test process.

 
Suggest Edits

Under the Hood

 
How it Works

How it Works

Wireless network operators have invested hundreds of billions of dollars to ensure highly reliable and precise mobile network. This fact ensures that your calls, text messages, and data make it to the right device at all times without failure.

Danal in partnership with Wireless Network Operators leverages this very network capability to verify the phone in session. When your app makes an API call, the Mobile Operator detects that data session and the phone number behind it. Danal’s platform then checks with the MNO systems to verify if the phone number sent by the user/app is indeed the phone number in the data session.

Danal’s technology uses the Mobile Network as the 2nd Factor in authentication. This proves to be a secure method which isn’t susceptible to any fraud and delivers the best user experience with no interruptions.

Danal is connected to all major operators in United States and other countries are coming soon. However, in scenarios where the device is on a non-mobile network, Danal’s platform automatically detects that and gracefully allows your app to switch to SMS based phone verification method.

 

Check out the Danal Phone Verification APIs in action yourself by visiting https://demo.phoneverification.io on your mobile phone.