Requests

Status Request

Upon completion of a verification request, you can inquire about the verification status by accessing the status endpoint. You’ll have to provide the reference ID for the desired verification and you will be promptly informed about the status of that verification.

Endpoint

POSThttps://api.facia.ai/status

Authorization:

client-secret: 'your_client_secret_key_here'
Description:

Make sure to include the client-secret in the headers for proper authorization. otherwise, you may encounter status:403 Forbidden.

Request Body Samples:

HTTP

//POST /status HTTP/1.1
//Host: api.facia.ai
//client-secret:
//Content-Type: application/json

{
"reference_id": "123456789012345"
}

Javascript

var myHeaders = new Headers();
myHeaders.append("client-secret", "ABC1231231XYZ12321312");
myHeaders.append("Content-Type", "application/x-www-form-urlencoded");

var urlencoded = new URLSearchParams();
urlencoded.append("reference_id", "123456789012345");

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: urlencoded,
  redirect: 'follow'
};

fetch("https://api.facia.ai/status", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Curl

curl --location 'https://api.facia.ai/status' \
--header 'client-secret;' \
--header 'Content-Type: application/json' \
--data '{
"reference_id": "DFG6TYJHGR567YH"
}'

PHP

<?php

  $curl = curl_init();

  curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://api.facia.ai/status',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => 'reference_id=123456789012345',
    CURLOPT_HTTPHEADER => array(
      'client-secret: ABC1231231XYZ12321312',
      'Content-Type: application/x-www-form-urlencoded'
    ),
  ));

  $response = curl_exec($curl);

  curl_close($curl);
  echo $response;

Python

import requests
url = "https://api.facia.ai/status"
payload='reference_id=123456789012345' headers = {
  'client-secret': 'ABC1231231XYZ12321312',
  'Content-Type': 'application/x-www-form-urlencoded'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)

Ruby

require "uri"
require "json"
require "net/http"

url = URI("https://api.facia.ai/status")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["client-secret"] = ""
request["Content-Type"] = "application/json"
request.body = JSON.dump({
  "reference_id": "DFG6TYJHGR567YH"
})

response = https.request(request)
puts response.read_body

java

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.charset.StandardCharsets;

public class CurlExample {

    public static void main(String[] args) throws Exception {
        String url = "https://api.facia.ai/status";
        String postData = "reference_id=123456789012345";
        String clientSecret = "ABC1231231XYZ12321312";
        URL apiUrl = new URL(url);
        HttpURLConnection connection = (HttpURLConnection) apiUrl.openConnection();
        connection.setRequestMethod("POST");
        connection.setDoOutput(true);
        connection.setDoInput(true);
        connection.setRequestProperty("client-secret", clientSecret);
        connection.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
        try (OutputStream os = connection.getOutputStream()) {
            byte[] postDataBytes = postData.getBytes(StandardCharsets.UTF_8);
            os.write(postDataBytes);
            os.flush();
        }
        try (BufferedReader in = new BufferedReader(new InputStreamReader(connection.getInputStream()))) {
            String inputLine;
            StringBuilder response = new StringBuilder();
            while ((inputLine = in.readLine()) != null) {
                response.append(inputLine);
            }
            System.out.println(response.toString());
        } finally {
            connection.disconnect();
        }
    }
}

C#

using System;
using System.IO;
using System.Net;
using System.Text;

class Program
{
    static void Main()
    {
        string url = "https://api.facia.ai/status";
        string postData = "reference_id=123456789012345";
        string clientSecret = "ABC1231231XYZ12321312";

        WebRequest request = WebRequest.Create(url);
        request.Method = "POST";

        request.Headers.Add("client-secret", clientSecret);
        request.ContentType = "application/x-www-form-urlencoded";

        using (StreamWriter writer = new StreamWriter(request.GetRequestStream()))
        {
            writer.Write(postData);
        }

        try
        {
            using (WebResponse response = request.GetResponse())
            using (Stream dataStream = response.GetResponseStream())
            using (StreamReader reader = new StreamReader(dataStream))
            {
                string responseFromServer = reader.ReadToEnd();
                Console.WriteLine(responseFromServer);
            }
        }
        catch (WebException ex)
        {
            Console.WriteLine(ex.Message);
        }
    }
}

Go

package main

import (
    "bytes"
    "fmt"
    "io/ioutil"
    "net/http"
)

func main() {
    url := "https://api.facia.ai/status"
    postData := "reference_id=123456789012345"
    clientSecret := "ABC1231231XYZ12321312"

    req, err := http.NewRequest("POST", url, bytes.NewBufferString(postData))
    if err != nil {
        fmt.Println("Error creating request:", err)
        return
    }

    req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
    req.Header.Set("client-secret", clientSecret)

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        fmt.Println("Error making request:", err)
        return
    }
    defer resp.Body.Close()

    body, err := ioutil.ReadAll(resp.Body)
    if err != nil {
        fmt.Println("Error reading response:", err)
        return
    }

    fmt.Println(string(body))
}

Request Parameter

Parameters	Description
reference_id	Required: Yes Type: String Example: reference_id="123456789012345" The reference id of the request against which the status should be retrieved.

Response Sample

{
    "status": true,
    "message": "Success",
    "result": {
        "data": {
            "reference_id": "123456789012345",
            "type": "photo_id_match",
            "status": "ACCEPTED",
            "similarity_score": 0.9115378856658936,
            "similarity_status": 1,
            "quick_liveness_image": "https://app.facia.ai/backend/api/get-proof/d2p4Z04wTWxUN3Q0WjhPYmJhc283bWVWOUh2clpHTnQ6NjVhNTBjNWM1MDEwMmI5NDdlMGEwMGI7",
            "video": null,
            "id_card_image": "https://app.facia.ai/backend/api/get-proof/TFhaYThwdzdVNldFOGlERm80QWtNaVgzMUVzVUZsV1Q6NjVhNTBjNWM1MDEwMmI5NDdlMGEwMGJ2",
            "video_frame_1": null,
            "video_frame_2": null
        }
    }
}

Response Parameter

Parameters	Description
reference_id	This contains the reference_id associated with the transaction. Example: reference_id : 123456789012345
type	Indicates the type of service that was performed.
status	This key tells about the updated status of the verification. Example: status: ACCEPTED
similarity_status	Type: string Example: similarity_status=1 1 means matched and 0 means not matched.
similarity_score	Type: string Example: similarity_score=0.98
quick_liveness_image	The URL contains the image proof that was provided/captured for the verification. Example: https://app.facia.ai/backend/api/get-proof/d2p4Z04wTWxUN3Q0WjhPYmJhc283bWVWOUh2clpHTnQ6NjVhNTBjNWM1MDEwMmI5NDdlMGEwMGI7
video	This key contains the recorded video of the image proof during the verification process.
id_card_image	This parameter contains the second image frame provided under face match service.

Note

To seamlessly access the image, please retrieve it within 15 minutes otherwise, the link will expire and you will have to make an API call again.

Delete Request

After completing a transaction, you may use the delete request endpoint to delete the transaction. Please provide the reference ID for that request, and you will promptly be informed about the deletion of the transaction.

Endpoint

POSThttps://api.facia.ai/delete

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 /delete HTTP/1.1
//Host: api.facia.ai
//client-secret:
//Content-Type: application/json

{
"reference": "reference to be deleted",
"comment": "add_your_comment_here"

}

Javascript

var myHeaders = new Headers();
myHeaders.append("client-secret", "ABC1231231XYZ12321312");
myHeaders.append("Content-Type", "application/x-www-form-urlencoded");

var urlencoded = new URLSearchParams();
urlencoded.append("reference_id", "123456789012345");
urlencoded.append("comment", "your_comment");

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: urlencoded,
  redirect: 'follow'
};

fetch("https://api.facia.ai/delete", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Curl

curl --location 'https://api.facia.ai/delete' \
--header 'client-secret;' \
--header 'Content-Type: application/json' \
--data '{
"reference": "JHR53TYTHYW18I9",
"comment": "add_your_comment_here"
}'

PHP

<?php

  $curl = curl_init();

  curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://api.facia.ai/delete',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => 'reference_id=123456789012345&comment=your_comment',
    CURLOPT_HTTPHEADER => array(
      'client-secret: ABC1231231XYZ12321312',
      'Content-Type: application/x-www-form-urlencoded'
    ),
  ));

  $response = curl_exec($curl);

  curl_close($curl);
  echo $response;

Python

import requests
url = "https://api.facia.ai/delete"
payload='reference_id=123456789012345&comment=your_comment' headers = {
  'client-secret': 'ABC1231231XYZ12321312',
  'Content-Type': 'application/x-www-form-urlencoded'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)

Ruby

require 'net/http'

url = URI("https://api.facia.ai/delete")
payload = 'reference_id=123456789012345&comment=your_comment'

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true if url.scheme == 'https'

request = Net::HTTP::Post.new(url)
request['client-secret'] = 'ABC1231231XYZ12321312'
request['Content-Type'] = 'application/x-www-form-urlencoded'
request.body = payload

response = http.request(request)

puts response.read_body

Java

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.charset.StandardCharsets;

public class Main {
    public static void main(String[] args) throws IOException {
        String url = "https://api.facia.ai/delete";
        String payload = "reference_id=123456789012345&comment=your_comment";

        URL apiUrl = new URL(url);
        HttpURLConnection connection = (HttpURLConnection) apiUrl.openConnection();
        connection.setRequestMethod("POST");
        connection.setRequestProperty("client-secret", "ABC1231231XYZ12321312");
        connection.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
        connection.setDoOutput(true);

        try (OutputStream os = connection.getOutputStream()) {
            byte[] postDataBytes = payload.getBytes(StandardCharsets.UTF_8);
            os.write(postDataBytes);
        }

        try (BufferedReader in = new BufferedReader(new InputStreamReader(connection.getInputStream()))) {
            String inputLine;
            StringBuilder response = new StringBuilder();

            while ((inputLine = in.readLine()) != null) {
                response.append(inputLine);
            }

            System.out.println(response.toString());
        } catch (IOException e) {
            System.out.println("Error reading response: " + e.getMessage());
        } finally {
            connection.disconnect();
        }
    }
}

C#

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

class Program
{
    static async Task Main()
    {
        string url = "https://api.facia.ai/delete";
        string payload = "reference_id=123456789012345&comment=your_comment";

        using (HttpClient client = new HttpClient())
        {
            client.DefaultRequestHeaders.Add("client-secret", "ABC1231231XYZ12321312");
            client.DefaultRequestHeaders.Add("Content-Type", "application/x-www-form-urlencoded");

            HttpResponseMessage response = await client.PostAsync(url, new StringContent(payload));

            if (response.IsSuccessStatusCode)
            {
                string responseContent = await response.Content.ReadAsStringAsync();
                Console.WriteLine(responseContent);
            }
            else
            {
                Console.WriteLine($"Error: {response.StatusCode} - {response.ReasonPhrase}");
            }
        }
    }
}

Go

package main

import (
    "bytes"
    "fmt"
    "io/ioutil"
    "net/http"
)

func main() {
    url := "https://api.facia.ai/delete"
    payload := "reference_id=123456789012345&comment=your_comment"

    req, err := http.NewRequest("POST", url, bytes.NewBufferString(payload))
    if err != nil {
        fmt.Println("Error creating request:", err)
        return
    }

    req.Header.Set("client-secret", "ABC1231231XYZ12321312")
    req.Header.Set("Content-Type", "application/x-www-form-urlencoded")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        fmt.Println("Error making request:", err)
        return
    }
    defer resp.Body.Close()

    body, err := ioutil.ReadAll(resp.Body)
    if err != nil {
        fmt.Println("Error reading response:", err)
        return
    }

    fmt.Println(string(body))
}

Request Parameter

Parameters	Description
reference	Required: Yes Type: String Example: reference="123456789012345" This is the unique reference ID of request which needs to be deleted.
comment	Required:Yes Type: String Maximum: 255 characters Add a comment why the request is deleted for your future reference.

Response Sample

{
    "status": true,
    "message": "Transaction has been deleted successfully!",
    "result": {
        "data": []
    }
}

Rate Limiting

To maintain optimal performance and ensure fair utilization of our service, Facia implements request limits for both Production and demo accounts. There are 60 requests that can be generated in one minute.

INFO

Please note that the rate limit mentioned is subject to change. If you require a different rate limit or have specific needs, please contact our Tech Support Team at [email protected] to discuss the possibility of adjusting the rate limit for your account.