Interactive

Facia’s Interactive KYC solution is designed for real-time, user-facing identity verification. It guides individuals through a seamless, step-by-step flow that includes liveness detection, facial matching, and document verification, address verification and AML, all within a secure and intuitive interface. This approach ensures maximum engagement and accuracy by capturing data directly from the end-user during the session. Ideal for digital onboarding, financial services, and any environment requiring real-time user authentication, the interactive mode enhances trust, reduces fraud risk, and supports regulatory compliance with minimal friction.

1. Quick Liveness detection
2. Document OCR
3. Face Match
4. Face Search
5. Document Verification
6. Address Verification
7. Anti Money Laundering (AML)

These components work together within a unified framework to deliver accurate results while reducing manual review and user friction.

Generate KYC URL

To generate the KYC verification, send a request to the following endpoint with the mentioned sample payload. The KYC URL can be obtained from the API at:

Endpoint

POSThttps://api.facia.ai/generate-liveness-url

Endpoint and field naming

This endpoint and its response field are named after liveness (generate-liveness-url, liveness_url) because the same endpoint is also used to generate liveness-only links. When is_kyc_request is set to true, the returned liveness_url opens the full KYC flow for the services you select (for example liveness, document OCR, document verification, address verification and AML), not a liveness check only. The names are kept as they are for backward compatibility.

Authorization:

Token Type: Bearer
Description:

This API utilizes Access token or Client-Secret key in header for authentication.

You can use your client_id and client_secret key when using the "/request-access-token" endpoint to obtain a Bearer token for authorization while connecting to this API. For additional details on Authorization, click Here

Request Body Samples:

HTTP

//POST /generate-liveness-url  HTTP/1.1
//Host: api.facia.ai
//Content-Type: application/json
//Authorization: Bearer <access-token-here>

{
    "is_kyc_request": true,
    "services": [
        "quick_liveness",
        "face_match",
        "face_search",
        "document_ocr",
        "document_verification",
        "address_verification",
        "aml"
    ],
    "redirect_url": "https://www.example.com",
    "callback_url": "https://www.example.exc.com",
    "customer_id": "your_customer_id_here",
    "customer_email": "test@example.com",
    "customer_name": "your_customer_name_here",
    "ttl": 60
}

Javascript

const accessToken = '<access-token-here>';
const url = 'https://api.facia.ai/generate-liveness-url';

const requestBody = {
    is_kyc_request: true,
    services: [
        "quick_liveness",
        "face_match","face_search",
        "document_ocr",
        "document_verification",
        "address_verification",
        "aml"
    ],
    redirect_url: "https://www.example.com",
    callback_url: "https://www.example.exc.com",
    customer_id: "your_customer_id_here",
    customer_email: "test@example.com",
    customer_name: "your_customer_name_here",
    ttl: 60
};

fetch(url, {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${accessToken}`
    },
    body: JSON.stringify(requestBody)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

Curl

curl -X POST https://api.facia.ai/generate-liveness-url \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <access-token-here>" \
-d '{
   "is_kyc_request": true,
   "services": ["quick_liveness", "face_match","face_search", "document_ocr", "document_verification", "address_verification", "aml"],
   "redirect_url": "https://www.example.com",
   "callback_url": "https://www.example.exc.com",
   "customer_id": "your_customer_id_here",
   "customer_email": "test@example.com",
   "customer_name": "your_customer_name_here",
   "ttl": 60
}'

PHP

<?php
$accessToken = '<access-token-here>';
$url = 'https://api.facia.ai/generate-liveness-url';

$data = [
    'is_kyc_request' => true,
    'services' => ['quick_liveness', 'face_match', 'face_search','document_ocr', 'document_verification', 'address_verification', 'aml'],
    'redirect_url' => 'https://www.example.com',
    'callback_url' => 'https://www.example.exc.com',
    'customer_id' => 'your_customer_id_here',
    'customer_email' => 'test@example.com',
    'customer_name' => 'your_customer_name_here',
    'ttl' => 60
];

$options = [
    'http' => [
        'header'  => "Content-Type: application/json\r\n" .
                     "Authorization: Bearer $accessToken\r\n",
        'method'  => 'POST',
        'content' => json_encode($data)
    ]
];

$context  = stream_context_create($options);
$response = file_get_contents($url, false, $context);
echo $response;

Python

import requests
import json

url = 'https://api.facia.ai/generate-liveness-url'
access_token = '<access-token-here>'

headers = {
    'Content-Type': 'application/json',
    'Authorization': f'Bearer {access_token}'
}

data = {
    "is_kyc_request": True,
    "services": ["quick_liveness", "face_match","face_search", "document_ocr", "document_verification", "address_verification", "aml"],
    "redirect_url": "https://www.example.com",
    "callback_url": "https://www.example.exc.com",
    "customer_id": "your_customer_id_here",
    "customer_email": "test@example.com",
    "customer_name": "your_customer_name_here",
    "ttl": 60
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

Ruby

require 'net/http'
require 'json'
require 'uri'

uri = URI('https://api.facia.ai/generate-liveness-url')
access_token = '<access-token-here>'

header = {
    'Content-Type' => 'application/json',
    'Authorization' => "Bearer #{access_token}"
}

data = {
    is_kyc_request: true,
    services: ["quick_liveness", "face_match","face_search", "document_ocr", "document_verification", "address_verification", "aml"],
    redirect_url: "https://www.example.com",
    callback_url: "https://www.example.exc.com",
    customer_id: "your_customer_id_here",
    customer_email: "test@example.com",
    customer_name: "your_customer_name_here",
    ttl: 60
}

http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Post.new(uri.path, header)
request.body = data.to_json

response = http.request(request)
puts response.body

Java

import java.io.*;
import java.net.*;
import java.nio.charset.StandardCharsets;

public class Main {
    public static void main(String[] args) throws IOException {
        String accessToken = "<access-token-here>";
        String urlString = "https://api.facia.ai/generate-liveness-url";
        URL url = new URL(urlString);
        
        HttpURLConnection connection = (HttpURLConnection) url.openConnection();
        connection.setRequestMethod("POST");
        connection.setRequestProperty("Content-Type", "application/json");
        connection.setRequestProperty("Authorization", "Bearer " + accessToken);
        connection.setDoOutput(true);

        String jsonBody = "{\n" +
                "    \"is_kyc_request\": true,\n" +
                "    \"services\": [\"quick_liveness\", \"face_match\",\"face_search\", \"document_ocr\", \"document_verification\", \"address_verification\", \"aml\"],\n" +
                "    \"redirect_url\": \"https://www.example.com\",\n" +
                "    \"callback_url\": \"https://www.example.exc.com\",\n" +
                "    \"customer_id\": \"your_customer_id_here\",\n" +
                "    \"customer_email\": \"test@example.com\",\n" +
                "    \"customer_name\": \"your_customer_name_here\",\n" +
                "    \"ttl\": 60\n" +
                "}";

        try (OutputStream os = connection.getOutputStream()) {
            byte[] input = jsonBody.getBytes(StandardCharsets.UTF_8);
            os.write(input, 0, input.length);
        }

        try (BufferedReader br = new BufferedReader(new InputStreamReader(connection.getInputStream(), StandardCharsets.UTF_8))) {
            String responseLine;
            StringBuilder response = new StringBuilder();
            while ((responseLine = br.readLine()) != null) {
                response.append(responseLine.trim());
            }
            System.out.println(response.toString());
        }
    }
}

C#

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        var accessToken = "<access-token-here>";
        var url = "https://api.facia.ai/generate-liveness-url";
        
        using (HttpClient client = new HttpClient())
        {
            client.DefaultRequestHeaders.Add("Authorization", $"Bearer {accessToken}");
            client.DefaultRequestHeaders.Add("Content-Type", "application/json");

            var data = new
            {
                is_kyc_request = true,
                services = new string[] { "quick_liveness", "face_match","face_search", "document_ocr", "document_verification", "address_verification", "aml" },
                redirect_url = "https://www.example.com",
                callback_url = "https://www.example.exc.com",
                customer_id = "your_customer_id_here",
                customer_email = "test@example.com",
                customer_name = "your_customer_name_here",
                ttl = 60
            };

            var json = Newtonsoft.Json.JsonConvert.SerializeObject(data);
            var content = new StringContent(json, Encoding.UTF8, "application/json");

            var response = await client.PostAsync(url, content);
            var result = await response.Content.ReadAsStringAsync();
            Console.WriteLine(result);
        }
    }
}

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "log"
    "net/http"
)

func main() {
    accessToken := "<access-token-here>"
    url := "https://api.facia.ai/generate-liveness-url"

    requestBody := map[string]interface{}{
        "is_kyc_request": true,
        "services": []string{
            "quick_liveness", "face_match","face_search", "document_ocr", "document_verification", "address_verification", "aml"
        },
        "redirect_url": "https://www.example.com",
        "callback_url": "https://www.example.exc.com",
        "customer_id": "your_customer_id_here",
        "customer_email": "test@example.com",
        "customer_name": "your_customer_name_here",
        "ttl": 60
    }

    jsonData, err := json.Marshal(requestBody)
    if err != nil {
        log.Fatal(err)
    }

    req, err := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
    if err != nil {
        log.Fatal(err)
    }

    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Authorization", "Bearer "+accessToken)

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        log.Fatal(err)
    }
    defer resp.Body.Close()

    fmt.Println("Response Status:", resp.Status)
}

Parameters	Description
is_kyc_request	Required: Yes (if doing kyc request) Type: Boolean Example: is_kyc_request=true This flag must be set to true to indicate that the request is for initiating a KYC process. If omitted, the link is treated as a liveness-only.
services	Required: Yes Type: Array of Strings Allowed values: quick_liveness, document_ocr, document_verification, face_match, face_search,address_verification, aml At least one service must be selected.
redirect_url	Required: No Type: String Example: redirect_url=https://www.example.com/?64db8940a619c1692109120 Indicates the URL to be used for post-transaction redirection.
callback_url	Required: No Type: String Example: callback_url=https://www.example.exc.com/ Multiple server-to-server calls are initiated to communicate updates on verification status to Facia’s clients.
customer_id	Required: No Type: String Example: customer_id=your_customer_id_here The ID of the customer for whom the link is being generated.
customer_email	Required: No Type: String Example: customer_email=test@example.com The email of the customer for whom the link is being generated.
customer_name	Required: No Type: String Example: customer_name=your_customer_name_here The name of the customer for whom the link is being generated.
ttl	Required: No Type: Integer Example: ttl=60 Minimum: 1 minute Maximum: 43200 minutes (30 days) Default: 60 minutes Specifies the time-to-live (TTL) in minutes, indicating the duration until the link expires.

Response Sample

{
  "status": true,
  "message": "Success",
  "result": {
    "data": {
      "liveness_url": "https://app.facia.ai/?64db8940a619c1692109120",
      "reference_id": "your_reference_id_here",
      "callback_url": "https://www.example.exc.com",
      "customer_id": "your_customer_id_here",
      "customer_email": "test@example.com",
      "customer_name": "your_customer_name_here",
      "redirect_url": "https://www.example.com"
    }
  }
}

Response Parameter

Parameters	Description
status	Type: Boolean Example: true or false Indicates whether the request was successful (true) or not (false).
message	Type: String Descriptive message corresponding to the request status.
errors	Type: Object (present only if status is false) contains errors explaining why the request failed.
result.data.liveness_url	Type: String The link the end user opens to complete the verification. When is_kyc_request is true, it opens the full KYC flow for the selected services; otherwise it opens a liveness-only check. The field keeps the name liveness_url in both cases for backward compatibility. Example: liveness_url=https://app.facia.ai/?64db8940a619c1692109120
result.data.reference_id	The unique identified associated with the created transaction.
result.data.callback_url	The link where the transaction response will be sent. Example: callback_url=https://www.example.exc.com/
result.data.customer_id	Type: String Contains the unique ID defined for the end user. Example: customer_id="your_customer_id_here"
result.data.customer_email	Type: String This key includes the email that belongs to the end user. Example: customer_email=test@example.com
result.data.customer_name	Type: String This key includes the name of the end user. Example: customer_name=your_customer_name_here
result.data.redirect_url	Indicate the URL to be used for post-transaction redirection.

Customer details

customer_id, customer_email and customer_name are returned only when customer details are sent in the request. If customer_id is sent without customer_email or customer_name, the fields that were not sent are returned as null.

iFrame Integration

Integrate the kyc iFrame into your platform to ensure users are physically present during interactions. Use the code snippet below to embed the iframe and pass the liveness_url (the KYC link) which you got in response of generate-liveness-url endpoint within the src attribute of the iFrame.

<iframe 
  src="liveness_url" 
  allow="camera" 
  style="width: 100%; height: 600px; border: none;"
></iframe>

For optimal user experience, we recommend:

• Minimum width: 375px
• Minimum height: 600px
• Responsive layout that adjusts to the container size