Validate a Phone Validation

POST https://api.verifik.co/v2/phone-validations/validate

This endpoint validates a one-time password (OTP) sent to a user's phone number as part of the phone verification process. It ensures the user-provided OTP is correct and updates the verification status accordingly.

Headers

Name	Value
Content-Type	application/json

Body

Name	Type	Required	Description
phone	string	Yes	The phone number that was used to create the phone validation.
countryCode	string	Yes	The country code of the phone number in format +XXX (e.g., +507 for Panama).
otp	number	Yes	The one-time password (OTP) that was sent to the user's phone number.
project	string	No	The unique identifier for the project (optional, helps narrow down the validation).
projectFlow	string	No	The unique identifier for the project flow (optional, helps narrow down the validation).
phoneGateway	string	No	The delivery method used: sms, whatsapp, or none.

Body Examples

Basic Validation

{
  "phone": "62647737",
  "countryCode": "+507",
  "otp": 123456
}

Advanced Validation with Project Details

{
  "phone": "62647737",
  "countryCode": "+507",
  "otp": 123456,
  "project": "507f1f77bcf86cd799439011",
  "projectFlow": "507f1f77bcf86cd799439015",
  "phoneGateway": "whatsapp"
}

Request

cURL

curl -X POST https://api.verifik.co/v2/phone-validations/validate \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "62647737",
    "countryCode": "+507",
    "otp": 123456
  }'

Node.js

const axios = require('axios');

const data = {
  phone: "62647737",
  countryCode: "+507",
  otp: 123456
};

axios.post('https://api.verifik.co/v2/phone-validations/validate', data, {
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error.response ? error.response.data : error.message);
});

Kotlin

import android.os.AsyncTask
import java.io.OutputStream
import java.net.HttpURLConnection
import java.net.URL

fun validatePhoneValidation() {
    val url = URL("https://api.verifik.co/v2/phone-validations/validate")
    val jsonBody = """
        {
          "phone": "62647737",
          "countryCode": "+507",
          "otp": 123456
        }
    """.trimIndent()
    
    AsyncTask.execute {
        with(url.openConnection() as HttpURLConnection) {
            requestMethod = "POST"
            setRequestProperty("Authorization", "Bearer YOUR_ACCESS_TOKEN")
            setRequestProperty("Content-Type", "application/json")
            doOutput = true
            
            // Write JSON body to the request
            outputStream.use { os: OutputStream ->
                val input = jsonBody.toByteArray(Charsets.UTF_8)
                os.write(input, 0, input.size)
            }
            
            // Read the response
            val responseCode = responseCode
            if (responseCode == HttpURLConnection.HTTP_OK) {
                inputStream.bufferedReader().use {
                    val response = it.readText()
                    println("Response: $response")
                }
            } else {
                println("Request failed with code: $responseCode")
            }
        }
    }
}

Swift

import Foundation

func validatePhoneValidation() {
    let url = URL(string: "https://api.verifik.co/v2/phone-validations/validate")!
    var request = URLRequest(url: url)
    request.httpMethod = "POST"
    request.setValue("Bearer YOUR_ACCESS_TOKEN", forHTTPHeaderField: "Authorization")
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    
    // JSON body
    let jsonBody: [String: Any] = [
        "phone": "62647737",
        "countryCode": "+507",
        "otp": 123456
    ]
    
    // Convert JSON to Data
    request.httpBody = try? JSONSerialization.data(withJSONObject: jsonBody, options: [])
    
    // Send request
    let task = URLSession.shared.dataTask(with: request) { data, response, error in
        if let error = error {
            print("Request error:", error)
            return
        }
        
        if let data = data, let responseString = String(data: data, encoding: .utf8) {
            print("Response data:", responseString)
        } else {
            print("Request failed with response: \(String(describing: response))")
        }
    }
    task.resume()
}

Response

The response will contain information about the validated phone validation, including the updated status and any additional data based on the validation type.

200

{
  "data": {
    "_id": "674de8df21c72be3cc42b8a7",
    "status": "validated",
    "countryCode": "+507",
    "phone": "62647737",
    "type": "validation",
    "showFaceLivenessRecommendation": false
  }
}

200 (Login Type)

{
  "data": {
    "_id": "674de8df21c72be3cc42b8a7",
    "status": "validated",
    "countryCode": "+507",
    "phone": "62647737",
    "type": "login",
    "showFaceLivenessRecommendation": true,
    "appLogin": {
      "id": "app-login-id",
      "status": "validated"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

403

{
  "code": "otp_does_not_match",
  "message": "403:otp_does_not_match"
}

404

{
  "code": "phone_validation_not_found",
  "message": "404:phone_validation_not_found"
}

412

{
  "code": "phoneValidation_has_expired",
  "message": "412:phoneValidation_has_expired"
}

Notes

• OTP Expiration: OTPs have a limited lifespan and will expire after a predefined time. Expired OTPs cannot be validated.

• Demo Mode: If the project is in demo mode, special demo OTPs may be accepted for testing purposes.

• Status Updates: Successful validation automatically updates the phone validation status to "validated".

• Webhook Events: Validation events trigger webhook notifications for tracking and integration purposes.

• Login Tokens: For login-type validations, a JWT token is returned for authenticated access.

• Face Liveness: Some project flows may recommend face liveness verification after phone validation.