Create an App Registration Phone Validation

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

A Phone Validation is an instance within Verifik's system that allows you to process and validate phone numbers during the app registration process. This process ensures the authenticity of user phone numbers and provides secure verification through SMS or WhatsApp delivery methods.

Headers

Name	Value
Content-Type	application/json
Authorization	Bearer <token>

The JWT Token you should use when creating App Registration Phone Validations is provided from the App Registration in creation.

Body

Name	Type	Description
project	string	The unique identifier for the project where this phone validation will be used.
validationMethod	string	The validation method, set to verificationCode.
phone	string	The phone number that will be validated (spaces will be automatically removed).
countryCode	string	The country code of the phone number in format +XXX (e.g., +507 for Panama).
type	string	Type of validation: validation, login, onboarding, or oneTimeLink.
expiresAt	string	Optional expiration date for the validation code.
redirectUrl	string	Optional URL for redirect after validation.
webhookUrl	string	Optional webhook URL for validation notifications.
identityUrl	string	Optional identity verification URL.
requires2FA	boolean	Optional flag indicating if two-factor authentication is required.
ipAddress	string	Optional IP address of the user.

validationMethod Values

Value	Description
verificationCode	Sends a one-time password (OTP) to the phone number for verification.

type Values

Value	Description
validation	General phone number validation. For general phone validations - you must use Create a Phone Validation
login	Phone verification during user login. For login phone validations - you must use Create a Phone Validation
onboarding	Phone verification during user registration.

Minimal Body Data

{
  "project": "507f1f77bcf86cd799439011",
  "validationMethod": "verificationCode",
  "phone": "62647737",
  "countryCode": "+507",
  "type": "onboarding"
}

Full Body Data

{
  "project": "507f1f77bcf86cd799439011",
  "validationMethod": "verificationCode",
  "phone": "62647737",
  "countryCode": "+507",
  "type": "validation",
  "expiresAt": "2024-12-31T23:59:59.000Z",
  "redirectUrl": "https://yourapp.com/success",
  "webhookUrl": "https://yourapp.com/webhook",
  "identityUrl": "https://yourapp.com/identity",
  "requires2FA": false,
  "ipAddress": "192.168.1.1"
}

Request

cURL

curl -X POST https://api.verifik.co/v2/phone-validations/app-registration \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "507f1f77bcf86cd799439011",
    "validationMethod": "verificationCode",
    "phone": "62647737",
    "countryCode": "+507",
    "type": "validation"
  }'

Node.js

const axios = require('axios');

const data = {
  project: "507f1f77bcf86cd799439011",
  validationMethod: "verificationCode",
  phone: "62647737",
  countryCode: "+507",
  type: "validation"
};

axios.post('https://api.verifik.co/v2/phone-validations/app-registration', 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 createPhoneValidation() {
    val url = URL("https://api.verifik.co/v2/phone-validations/app-registration")
    val jsonBody = """
        {
          "project": "507f1f77bcf86cd799439011",
          "validationMethod": "verificationCode",
          "phone": "62647737",
          "countryCode": "+507",
          "type": "validation"
        }
    """.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 createPhoneValidation() {
    let url = URL(string: "https://api.verifik.co/v2/phone-validations/app-registration")!
    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] = [
        "project": "507f1f77bcf86cd799439011",
        "validationMethod": "verificationCode",
        "phone": "62647737",
        "countryCode": "+507",
        "type": "validation"
    ]
    
    // 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 new Phone Validation instance. Important fields include the unique identifier _id, the status of the validation process, and the encrypted OTP that was sent to the user.

200

{
  "data": {
    "client": "507f1f77bcf86cd799439013",
    "project": "507f1f77bcf86cd799439011",
    "projectFlow": "507f1f77bcf86cd799439015",
    "status": "sent",
    "countryCode": "+507",
    "phone": "62647737",
    "phoneGateway": "whatsapp",
    "otp": "$2a$10$/v55.1QmwlCdX6zD1jy51OF87POIDZzj30.UmTtp13pZv6uKm.a.m",
    "expiresAt": "2024-12-02T17:15:35.000Z",
    "phoneData": {},
    "type": "validation",
    "redirectUrl": "https://api.verifik.co",
    "requires2FA": false,
    "ipAddress": "172.17.0.1",
    "language": "en",
    "_id": "674de8df21c72be3cc42b8a7",
    "updatedAt": "2024-12-02T17:05:36.788Z",
    "createdAt": "2024-12-02T17:05:36.788Z",
    "__v": 0,
    "new": true
  }
}

409

{
  "code": "MissingParameter",
  "message": "Invalid countryCode format. CountryCode should be in the format + followed by 1 to 3 digits."
}

Notes

• Country Code Format: The countryCode must be in the format +XXX where X are digits (1-3 digits maximum).

• Phone Number: Spaces in phone numbers are automatically removed during processing.

• OTP Security: The OTP is encrypted using bcrypt before storage for security.

• Default Gateway: Phone validations default to WhatsApp delivery method.

• Automatic Linking: When created through the app-registration endpoint, the phone validation is automatically linked to the user's app registration record.