Rest API

IMPORTANT NOTE

For the security of your application, you must make sure to send the IP address of the end user in all requests. To do this, you need to add X-Vfk-Forwarded-For header parameter in all requests.

Validation Method List

You can get verification methods and localization texts to prepare your verification screens. By sending "lang" value as a query parameter you can control the language of the localization texts in the response.

lang

Language of end user. Default value is 'en' (English). This parameter is not required.Response includes specific warning messages in cases of errors for developers to act upon.

Validation Method List

curl --request GET 'https://web-rest.verifykit.com/v1.0/init?lang=en' --header 'X-Vfk-Server-Key: YOUR-SERVER-KEY' --header 'X-Vfk-Forwarded-For: END-USER-IP-ADDRESS' --header 'Content-Type: application/json'

{
    "meta": {
        "requestId": "REQUEST-ID",        
        "httpStatusCode": 200    
    },    
    "result": {
        "list": [
            {
                "appPackage": "whatsapp",                
                "name": "WhatsApp",                
                "app": "whatsapp",                
                "text": "Verify via WhatsApp",                
                "textColour": "ffffff",                
                "bgColour": "1bd741",                
                "icon": "https://web-rest.verifykit.com/img/web/[email protected]"            
            },            
            {
                "appPackage": "telegram",                
                "name": "Telegram",                
                "app": "telegram",                
                "text": "Verify via Telegram",                
                "textColour": "ffffff",                
                "bgColour": "61a8de",                
                "icon": "https://web-rest.verifykit.com/img/web/[email protected]"            
            },            
            {
                "appPackage": "otp",                
                "name": "Sms",                
                "app": "otp",                
                "text": "Click to verify via SMS",                
                "textColour": "ffffff",                
                "bgColour": "cbcbd0",                
                "icon": "https://web-rest.verifykit.com/img/web/[email protected]"            
            }        
        ],
        "description": "Please tap on your preferred messaging app and send us the code appearing on the screen.",        
        "localizationList": [
            {
                "key": "validation.description",                
                "value": "Please tap on your preferred messaging app and send us the code appearing on the screen."            
            },            
            {
                "key": "validation.chooseAppText",                
                "value": "Select a messaging app to verify your phone number."            
            },            
            .            
            .            
            .
        ],        
        "messages": []    
    }
}

// composer require verifykit/verifykit-sdk-php
$vfk = new VerifyKitWeb($serverKey, $clientIp);
/** @var VerifyKitEntityValidationMethodList $validationMethodList */
$validationMethodList = $vfk->getValidationMethodList();
/** @var VerifyKitEntityValidationMethod $validationMethod */
foreach ($validationMethodList->getList() as $validationMethod) {
    // $validationMethod-> getName, getApp, getText, getTextColour, getBgColour, getIcon...
}
// if you want to handle all localizations for validation steps, use this way.
/** @var VerifyKitEntityLocalization $localization */
foreach ($validationMethodList->getLocalizationList() as $localization){
    // getKey, getValue of localization.
}

Depending on your selection of OTP view themes on your application detail screen in VerifyKit Panel, the response structure of the init request changes.

If you choose "Recommended Theme" in VerifyKit Panel, OTP settings will be given in the list array parameter of the response. If you choose the "Basic Theme" setting in VerifyKit Panel, OTP view settings will be given in two different parameters in the root of the response as "alternativeValidationDescription" and "alternativeValidation".

Response Examples

{
    "meta": {
            "requestId": "REQUEST-ID",        
            "httpStatusCode": 200    
    },    
    "result": {
            "list": [],        
            "alternativeValidation": "otp",        
            "alternativeValidationDescription": "Don't use any of these apps?",        
            "description": "Please tap on your preferred messaging app and send us the code appearing on the screen.",        
            "localizationList": [
                {
                        "key": "validation.description",                
                        "value": "Please tap on your preferred messaging app and send us the code appearing on the screen."            
                },            
                {
                        "key": "validation.chooseAppText",                
                        "value": "Select a messaging app to verify your phone number."            
                },            
                .            
                .            
                .        
        ],        
        "messages": []    
    }
}

{
    "meta": {
            "requestId": "REQUEST-ID",        
            "httpStatusCode": 200    
            },    
            "result": {
                "list": [
                    {
                        "appPackage": "otp",              
                        "name": "Sms",              
                        "app": "otp",              
                        "text": "Click to verify via SMS",              
                        "textColour": "ffffff",              
                        "bgColour": "cbcbd0",              
                        "icon": "https://web-rest.verifykit.com/img/web/[email protected]"            
                     }        
            ],        
            "description": "Please tap on your preferred messaging app and send us the code appearing on the screen.",        
            "localizationList": [
               {
                      "key": "validation.description",                
                      "value": "Please tap on your preferred messaging app and send us the code appearing on the screen."            
               },            
               {
                      "key": "validation.chooseAppText",                
                      "value": "Select a messaging app to verify your phone number."            
                },            
                .            
                .            
                .        
            ],        
            "messages": []    
        }
}

Start Validation (WhatsApp)

When your users choose a validation method from the screen you prepare, you can start the validation process by using the request parameters stated below. Request Parameters appThis parameter represents the application you want to use in this verification instance. Could be “whatsapp”. langLanguage of end user. Default value is 'en' (English). This parameter is not required. deeplinkDetermines if the deep link parameter will be returned in the response.If you send deeplink parameter as boolean true you will receive a deeplink parameter in the response. Useful if you integrate Rest Api for mobile applications or mobile web browsers. qrCodeDetermines if the qrCode parameter will be returned in the response. If you send qrCode parameter as boolean true, you will receive a base64 qrCode png string. By showing this qrCode to users coming from desktop browsers, you can make it easier to verify.We recommend that you do not send qrCode parameter as boolean true for requests from mobile applications or mobile browsers. You should use deeplink for these platforms."deeplink" and "qrCode" parameters cannot be boolean true at the same time. If you send both parameters as boolean true at the same time, we will only give the deeplink parameter in the response.Default value is true for deeplink, and false for qrCode. These parameters are not required.

phoneNumber If you add this parameter to request, WhatsApp will work as OTP. This parameter is not required. For example: +90_____ Response Parameters referenceThis parameter is the code given to you in order to track the verification process on our end. You will use this string for the rest of the verification requests. qrCodeThis parameter is the base64 encoded png string which you can use as an image to help your users open WhatsApp depending on the "app" parameter you have sent. deeplinkThis parameter is used to open the application in which your users will verify on their mobile devices depending on the "app" parameter you have sent with the request.

curl  --request POST 'https://web-rest.verifykit.com/v1.0/start' \
--header 'X-Vfk-Server-Key: YOUR-SERVER-KEY' \
--header 'X-Vfk-Forwarded-For: END-USER-IP-ADDRESS' \
--header 'Content-Type: application/json' \
-d '{"app":"whatsapp", "phoneNumber:"+90...."}'

{
    "meta": {
        "requestId": "REQUEST-ID",        
        "httpStatusCode": 200    
    },    
    "result": {        
        "deeplink": "https://wa.me/905395744034?text=.....",        
        "qrCode": "data:image/png;base64,iVBORw0KGgoAA......",        
        "reference": "111111"    
    }
}

$vfk = new VerifyKitWeb($serverKey, $clientIp);
$validationMethod = 'whatsapp';
/** @var VerifyKitEntityValidationStart $result */
$validationStart = $vfk->startValidation($validationMethod, $lang, $deeplink, $qrCode);
// if you want to redirect your user for validation, get deeplink.
echo $validationStart->getDeeplink();
// if you want to view a Qr code to your user for validation, get base64 png string and set it as an image source on web browsers.
echo $validationStart->getQrCode();
// keep this reference code for next step.
echo $validationStart->getReference();

Check Validation (WhatsApp)

With the "reference" code you received in the previous response, you can check whether the validation has been completed by the user or not.

If your user has completed the validation, you will receive a "session id" of this validation in the response.

curl  --request POST 'https://web-rest.verifykit.com/v1.0/start' --header 'X-Vfk-Server-Key: YOUR-SERVER-KEY' --header 'X-Vfk-Forwarded-For: END-USER-IP-ADDRESS' --header 'Content-Type: application/json' -d '{"app":"whatsapp"}'

{
    "meta": {
        "requestId": "REQUEST-ID",        
        "httpStatusCode": 200    
    },    
    "result": {
        "deeplink": "https://wa.me/905395744034?text=.....",        
        "qrCode": "data:image/png;base64,iVBORw0KGgoAA......",        
        "reference": "111111"    
    }
}

$vfk = new VerifyKitWeb($serverKey, $clientIp);
$validationMethod = 'whatsapp';
/** @var VerifyKitEntityValidationStart $result */
$validationStart = $vfk->startValidation($validationMethod, $lang, $deeplink, $qrCode);
// if you want to redirect your user for validation, get deeplink.
echo $validationStart->getDeeplink();
// if you want to view a Qr code to your user for validation, get base64 png string and set it as an image source on web browsers.
echo $validationStart->getQrCode();
// keep this reference code for next step.
echo $validationStart->getReference();

Check Validation (WhatsApp OTP)

With the "reference" code you received in the previous response, you can check whether the validation has been completed by the user or not.

In WhatsApp OTP, you must add the code parameter to the check request. This parameter is required.

If your user has completed the validation, you will receive a "session id" of this validation in the response.

curl  --request POST 'https://web-rest.verifykit.com/v1.0/check-whatsapp' \
--header 'X-Vfk-Server-Key: YOUR-SERVER-KEY' \
--header 'X-Vfk-Forwarded-For: END-USER-IP-ADDRESS' \
--header 'Content-Type: application/json' \
-d '{"reference":"REFERENCE-OF-VALIDATION", "code":"111111"}'

Start Validation (OTP)

Country List

Firstly, prepare a screen where your user will enter their phone number and country code. While preparing this screen, you can get the list of country information such as country code and phone code by sending a request to the "/country" endpoint like the example below.

Other parameters you can send at this request: countryCode

Country code parameter for the request. We return the sent countryCode parameter at the top of the list in the response. If you want a specific country (user's country detected by ip on your side for example) to be the first response parameter, you can send countryCode with your request. Not required.

curl  --request POST 'https://web-rest.verifykit.com/v1.0/country' --header 'Content-Type: application/json' --header 'X-Vfk-Forwarded-For: END-USER-IP-ADDRESS' --header 'X-Vfk-Server-Key: YOUR-SERVER-KEY'

{
    "meta": {
        "requestId": "REQUEST-ID",        
        "httpStatusCode": 200    
    },    
    "result": {        
        "list": [
            {    "phoneCode": "string",
                 "countryCode": "string",                
                 "title": "string"            
             },         
         ]    
     }
 }

$vfk = new VerifyKitWeb($serverKey, $clientIp);
$countryCode = "TR";
$result = $vfk->getCountryList($countryCode);
/** @var VerifyKitEntityCountry $country */
foreach ($result->getCountryList() as $country){
    echo $country->getPhoneCode(); // phone code.
    echo $country->getCountryCode(); // country code    
    echo $country->getTitle(); // country name

Send OTP Request

Then, you must post the country code and the phone number that your user entered. The response you receive includes the "reference" you will use for checking status and the validity period of this verification. During this period, a validation code will be sent to the phone number that was entered by your user. Proceed to the next step to continue verification with the user-entered code.

Other parameters you can send at this request:

For OTP verification to work best, you should send us the MCC and MNC code of the sim card in the user's device.

mcc

Mobile Country Code (MCC) of the sim card in the user's device. Default value is '999'. Not required.

mnc

Mobile Network Code (MNC) of the sim card in the user's device. Default value is '999'. Not required.

lang

Language of end user. Default value is 'en' (English). You can set the language of the sent message. This parameter is not required.

curl  --request POST 'https://web-rest.verifykit.com/v1.0/send-otp' --header 'X-Vfk-Server-Key: YOUR-SERVER-KEY' --header 'X-Vfk-Forwarded-For: END-USER-IP-ADDRESS' --header 'Content-Type: application/json' -d '{"phoneNumber":"PHONE_NUMBER","countryCode":"COUNTRY_CODE"}'

{
    "meta": {
        "requestId": "REQUEST-ID",        
        "httpStatusCode": 201    
    },    
    "result": {
            "reference": "123456",        
            "timeout": 300    
    }
}

$vfk = new VerifyKitWeb($serverKey, $clientIp);
$phoneNumber = '+90........'; // End user phone number.
$countryCode = 'TR';
$mcc = '999';
$mnc = '999';
$lang = 'en';,
/** @var VerifyKitEntityOTPSend $result */
$result = $vfk->sendOTP($phoneNumber, $countryCode, $mcc, $mnc, $lang);
$reference = $result->getReference(); // This parameter is required for a check OTP request.

Check Validation (OTP)

With the "reference" code you received in the previous response, you can check whether the validation has been completed by the user or not.

If your user has completed the validation, you will receive a "session id" of this validation in the response which means the verification process sucessfully finished.

curl  --request POST 'https://web-rest.verifykit.com/v1.0/check-otp' --header 'X-Vfk-Server-Key: YOUR-SERVER-KEY' --header 'X-Vfk-Forwarded-For: END-USER-IP-ADDRESS' --header 'Content-Type: application/json' -d '{"phoneNumber":"PHONE_NUMBER","countryCode":"COUNTRY_CODE","reference":"REFERENCE-OF-VALIDATION","code":"USER-ENTERED-CODE"}'

{
    "meta": {
        "requestId": "REQUEST-ID",        
        "httpStatusCode": 200    
    },    
    "result": {
        "validationStatus": true,        
        "sessionId": "QWERTY123456"    
    }
}

$vfk = new VerifyKitWeb($serverKey, $clientIp);
$phoneNumber = '+90........'; // End user phone number.
$countryCode = 'TR';$reference = "111111"; // reference from sendOtp step.
$code = "123456"; // The code to be entered by the user receiving the OTP.
/** @var VerifyKitEntityOtpCheck $validation */
$otpCheck = $vfk->checkOtp($phoneNumber, $countryCode, $reference, $code);
if ($otpCheck->getValidationStatus()) {
    $sessionId = $otpCheck->getSessionId(); // session id for the OTP validation result
}

Last Step : Complete Validation

This is where you will get your user's credentials such as phone number et cetera. You can complete the validation by sending the "session id" parameter of the validation here. It is important to note that the domain for the post request is different from previous requests. For this last step only, you need to post the following request to https://api.verifykit.com domain in order to obtain the data of your verified user and complete validation process.

curl  --request POST 'https://api.verifykit.com/v1.0/result' --header 'X-Vfk-Server-Key: YOUR-SERVER-KEY' --header 'X-Vfk-Forwarded-For: END-USER-IP-ADDRESS' --header 'Content-Type: application/json' -d '{"sessionId":"SESSION-ID-OF-VALIDATION"}'

{
 "meta": {
     "requestId": "REQUEST-ID", 
     "httpStatusCode": 200 
 }, 
 "result": {
     "validationType": "whatsapp", 
     "validationDate": "Y-m-d H:i:s", 
     "phoneNumber": "+9......", 
     "countryCode": "TR" 
 }
}

$vfk = new VerifyKitVerifyKit($serverKey, $clientIp);
/** @var VerifyKitEntityResponse 
$result */$result = $vfk->getResult($sessionId);
if ($result->isSuccess()) {
    echo "Phone number : " . $result->getPhoneNumber() .
        ", Validation Type : " . $result->getValidationType() .
        ", Validation Date : " . $result->getValidationDate()->format('Y-m-d H:i:s') . PHP_EOL;
} else {
    echo "Error message : " . $result->getErrorMessage() . ", error code : " . $result->getErrorCode() . PHP_EOL;
}

from VerifyKit import Verify
verify = Verify(server_key="{SERVER-KEY}")
verify.validation(session_id='{SESSION-ID}')
if verify.is_valid:
    #Validation success.    
    print(verify.response())
elif verify.is_valid == False:
    #Validation fail.    
    print(verify.response())

const VerifyKit = require('verifykit')
const verifyKit = new VerifyKit("server_key");
verifyKit.validate('session_id').then(response => {
    console.log('Success');
}).catch(error => {
    console.log('Verification Failed')
});

Need some help?

We all need a little help sometimes. If you have any question or request, feel free to create an issue.

Error Codes

HTTP Status Code

Error Code

Description

400

400007

Invalid phone number, please check the phone number.

403

403004

You must send either qrCode or deeplink parameter as true in order to start verification.

403

403011

Validation type is not active.

403

403012

Phone number is banned.

403

403013

OTP Validation not found.

403

403014

OTP code is invalid.

403

403015

You have reached the limit of sending OTP code.

403

403036

Validation not found.

403

403037

Validation has expired.

403

403038

Undefined application. Please check your credential parameters.

403

403041

You have reached the limit of package validation count.

403

403042

Please check your account balance on VerifyKit Dashboard.

403

403043

Please check your account balance on VerifyKit Dashboard.

403

403048

Email is invalid.

403

403047

OTP setting is not active.

403

403049

OTP can only be used with test numbers.

429

429001

Too many requests. please try again later.

500

500008

Internal server error.

Error Response

Response

{
    "meta": {
        "requestId": "REQUEST-ID",        
        "httpStatusCode": "HTTP_STATUS_CODE",        
        "errorMessage": "ERROR_MESSAGE",        
        "errorCode": "ERROR_CODE"    
    }
}

PreviousWeb SDK

Last updated 2 years ago