Face Search (1:N)

In FACIA, the Face Search 1:N service plays a pivotal role by employing a robust facial search algorithm. This algorithm adeptly identifies similarities between a Selfie (Photo) and our comprehensive Image Database. Operating on a versatile 1:N matching approach, it allows users to seamlessly compare against multiple images in the database.

Create Face Search Transaction

This endpoint initiates a transaction request for the face search algorithm and returns a reference_id if the request includes proper authentication and valid fields, as mentioned below in the request parameters, using the POST method.

Endpoint

POSThttps://api.facia.ai/face-search

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:

//POST /face-search  HTTP/1.1
//Host: https://api.facia.ai
//Content-Type: application/json
//Authorization: Bearer <access-token-here>

{
  "type": "face_search",
  "file": "file.jpg",
  "client_reference":"QWERTY12345",
  "allow_override":0,
  "enroll_face":false
}

var myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer token");

var formdata = new FormData();
formdata.append("type", "face_search");
formdata.append("enroll_face", true);
formdata.append("file", fileInput.files[0], "321238932_678447270428202_3141578377253799698_n.jpeg");
formdata.append("client_reference", "QWERTY12345");
formdata.append("allow_override", false);

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

fetch("/face-search", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

curl --location 'https://api.facia.ai/face-search' \
--header 'Content-Type: application/json' \
--data '{
  "type": "face_search",
  "file": file.jpg,
  "client_reference":"QWERTY12345",
  "allow_override":false,
  "enroll_face": true,
}'

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => '/face-search',
  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 => array('client_reference' => 'QWERTY12345',"allow_override":false,"enroll_face":true,'file'=> new CURLFILE('/321238932_678447270428202_3141578377253799698_n.jpeg')),
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer token'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import requests

url = "/face-search"

payload={'client_reference': 'QWERTY12345','allow_override':false, 'enroll_face':true}

files=[
  ('file',('321238932_678447270428202_3141578377253799698_n.jpeg',open('/321238932_678447270428202_3141578377253799698_n.jpeg','rb'),'image/jpeg'))
]
headers = {
  'Authorization': 'Bearer token'
}

response = requests.request("POST", url, headers=headers, data=payload, files=files)

print(response.text)

require 'net/http'
require 'uri'

url = URI.parse('/face-search')
token = 'your_token'
payload = {
  'client_reference' => 'QWERTY12345',
  'allow_override' => false,
  'enroll_face'=>true,
  'file' => File.new('/path/to/321238932_678447270428202_3141578377253799698_n.jpeg', 'rb')
}
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url.path)
request['Authorization'] = "Bearer #{token}"
request.set_form(payload, 'multipart/form-data')
response = http.request(request)
puts "Response Code: #{response.code}"
puts "Response Body: #{response.body}"

import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.File;
import java.io.FileInputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URI;
import java.net.URL;

public class FaceSearchRequest {

    public static void main(String[] args) {
        try {
            String url = "/face-search";
            String token = "your_token";
            String payload = "client_reference=QWERTY12345&allow_override=false&enroll_face=false";
            String filePath = "/path/to/321238932_678447270428202_3141578377253799698_n.jpeg";
            File file = new File(filePath);
            URL uri = new URI(url).toURL();
            HttpURLConnection connection = (HttpURLConnection) uri.openConnection();
            connection.setRequestMethod("POST");
            connection.setDoOutput(true);
            connection.setRequestProperty("Authorization", "Bearer " + token);
            connection.setRequestProperty("Content-Type", "multipart/form-data; boundary=--------------------------123456789012345678901234");
            DataOutputStream outputStream = new DataOutputStream(connection.getOutputStream());
            outputStream.writeBytes("--" + "--------------------------123456789012345678901234" + "\r\n");
            outputStream.writeBytes("Content-Disposition: form-data; name=\"client_reference\"\r\n\r\nQWERTY12345\r\n");
            outputStream.writeBytes("--" + "--------------------------123456789012345678901234" + "\r\n");
            outputStream.writeBytes("Content-Disposition: form-data; name=\"allow_override\"\r\n\r\nfalse\r\n");
            outputStream.writeBytes("--" + "--------------------------123456789012345678901234" + "\r\n");
            outputStream.writeBytes("Content-Disposition: form-data; name=\"file\"; filename=\"" + file.getName() + "\"\r\n");
            outputStream.writeBytes("Content-Type: image/jpeg\r\n\r\n");
            FileInputStream fileInputStream = new FileInputStream(file);
            byte[] buffer = new byte[4096];
            int bytesRead;
            while ((bytesRead = fileInputStream.read(buffer)) != -1) {
                outputStream.write(buffer, 0, bytesRead);
            }
            outputStream.writeBytes("\r\n");
            fileInputStream.close();
            outputStream.writeBytes("--" + "--------------------------123456789012345678901234" + "--\r\n");
            outputStream.flush();
            int responseCode = connection.getResponseCode();
            BufferedReader reader = new BufferedReader(new InputStreamReader(connection.getInputStream()));
            StringBuilder response = new StringBuilder();
            String line;
            while ((line = reader.readLine()) != null) {
                response.append(line);
            }
            reader.close();
            System.out.println("Response Code: " + responseCode);
            System.out.println("Response Body: " + response.toString());
            connection.disconnect();
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

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

class Program
{
    static async Task Main()
    {
        string apiUrl = "/face-search";
        string token = "your_token";
        var payload = new MultipartFormDataContent
        {
            { new StringContent("QWERTY12345"), "client_reference" },
            { new StringContent("false"), "allow_override" },
            { new StringContent("false"), "enroll_face" },
            { new StreamContent(File.OpenRead("/path/to/321238932_678447270428202_3141578377253799698_n.jpeg")), "file", "321238932_678447270428202_3141578377253799698_n.jpeg" }
        };
        using (var httpClient = new HttpClient())
        {
            httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
            var response = await httpClient.PostAsync(apiUrl, payload);
            Console.WriteLine($"Response Code: {response.StatusCode}");
            string responseBody = await response.Content.ReadAsStringAsync();
            Console.WriteLine($"Response Body: {responseBody}");
        }
    }
}

package main

import (
    "bytes"
    "fmt"
    "io"
    "mime/multipart"
    "net/http"
    "os"
)

func main() {
    apiURL := "/face-search"
    token := "your_token"
    payload := &bytes.Buffer{}
    writer := multipart.NewWriter(payload)

    _ = writer.WriteField("client_reference", "QWERTY12345")
    _ = writer.WriteField("allow_override", "false")
    _ = writer.WriteField("enroll_face", "false")


    file, err := os.Open("/path/to/321238932_678447270428202_3141578377253799698_n.jpeg")
    if err != nil {
        fmt.Println("Error opening file:", err)
        return
    }
    defer file.Close()

    part, err := writer.CreateFormFile("file", file.Name())
    if err != nil {
        fmt.Println("Error creating form file:", err)
        return
    }
    _, err = io.Copy(part, file)
    if err != nil {
        fmt.Println("Error copying file to form:", err)
        return
    }
    _ = writer.Close()
    request, err := http.NewRequest("POST", apiURL, payload)
    if err != nil {
        fmt.Println("Error creating request:", err)
        return
    }
    request.Header.Set("Content-Type", writer.FormDataContentType())
    request.Header.Set("Authorization", "Bearer "+token)
    client := &http.Client{}
    response, err := client.Do(request)
    if err != nil {
        fmt.Println("Error making request:", err)
        return
    }
    defer response.Body.Close()
    fmt.Println("Response Code:", response.Status)
    responseBody, err := io.ReadAll(response.Body)
    if err != nil {
        fmt.Println("Error reading response body:", err)
        return
    }
    fmt.Println("Response Body:", string(responseBody))
}

Request Parameter

Parameters	Description
type	Required: Yes Type: string Example: `type=face_search` Type must be face_search.
file	Required: Yes Type: file Example: `file=file` File must be of type .jpeg, .jpg or .png.
client_reference	Required: No Type: string Minimum: 5 characters Maximum: 255 characters Example: `client_reference="QWERTY12345"` Required if allow_override field set to 1.
allow_override	Required: No Type: boolean Default value: 0 Accepted values: 0,1 The client reference is mandatory if the value of the override key is set as 1. The override key allow the system to replace the latest previous image with the new one against the specified reference number of the client’s reference.
enroll_face	Required: No Type: boolean Example: `enroll_face=true` Default value: true If you do not want the system to enroll the face then set the value of the key as false.

Response Sample

{
  "status": true,
  "message": "Transaction Created",
  "result": {
    "data": {
      "reference_id": "W4437KIWN0KDM13"
    }
  }
}

Response Parameter

Parameters	Description
reference_id	Type: string Example: `reference_id=W4437KIWN0KDM13` The unique identifier associated with the created transaction.
message	Type: string Example: `message=Transaction Created`

Face Search Result

This endpoint accepts a single field in the body request payload: reference_id. Once the backend finalizes the response, this endpoint returns a face_search_response object with multiple object ids of images that share the most similar features with the provided image. Failure to provide a valid reference_id will result in a 422 status code.

Endpoint

POSThttps://api.facia.ai/result

Authorization:

Token Type: Bearer
Description:

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

Request Body Samples:

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

{
  "reference_id": "W4437KIWN0KDM13"
}

var myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer token");

var formdata = new FormData();
formdata.append("reference_id", "W4437KIWN0KDM13");

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

fetch("/result", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

curl --location 'https://api.facia.ai/result' \
--header 'Content-Type: application/json' \
--data '{
  "reference_id": "W4437KIWN0KDM13"
}'

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => '/result',
  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 => array(),
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer token'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import requests

url = "/result"

payload={}
files=[

]
headers = {
  'Authorization': 'Bearer token'
}

response = requests.request("POST", url, headers=headers, data=payload, files=files)

print(response.text)

require 'net/http'
require 'uri'

url = URI.parse('/result')
token = 'your_token'
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url.path)
request['Authorization'] = "Bearer #{token}"
response = http.request(request)
puts "Response Code: #{response.code}"
puts "Response Body: #{response.body}"

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;

public class FaceSearchResultRequest {

    public static void main(String[] args) {
        try {
            String apiUrl = "/result";
            String token = "your_token";
            URL url = new URL(apiUrl);
            HttpURLConnection connection = (HttpURLConnection) url.openConnection();
            connection.setRequestMethod("POST");
            connection.setDoOutput(true);
            connection.setRequestProperty("Authorization", "Bearer " + token);
            int responseCode = connection.getResponseCode();
            BufferedReader reader = new BufferedReader(new InputStreamReader(connection.getInputStream()));
            StringBuilder response = new StringBuilder();
            String line;

            while ((line = reader.readLine()) != null) {
                response.append(line);
            }

            reader.close();
            System.out.println("Response Code: " + responseCode);
            System.out.println("Response Body: " + response.toString());
            connection.disconnect();
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

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

class Program
{
    static async Task Main()
    {
        string apiUrl = "/result";
        string token = "your_token";
        using (var httpClient = new HttpClient())
        {
            var request = new HttpRequestMessage(HttpMethod.Post, apiUrl);
            request.Headers.Add("Authorization", "Bearer " + token);
            var response = await httpClient.SendAsync(request);
            Console.WriteLine($"Response Code: {response.StatusCode}");
            string responseBody = await response.Content.ReadAsStringAsync();
            Console.WriteLine($"Response Body: {responseBody}");
        }
    }
}

package main

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

func main() {
    apiURL := "/result"
    token := "your_token"
    client := &http.Client{}
    request, err := http.NewRequest("POST", apiURL, nil)
    if err != nil {
        fmt.Println("Error creating request:", err)
        return
    }
    request.Header.Set("Authorization", "Bearer "+token)
    response, err := client.Do(request)
    if err != nil {
        fmt.Println("Error making request:", err)
        return
    }
    defer response.Body.Close()
    fmt.Println("Response Code:", response.Status)
    responseBody, err := ioutil.ReadAll(response.Body)
    if err != nil {
        fmt.Println("Error reading response body:", err)
        return
    }
    fmt.Println("Response Body:", string(responseBody))
}

Request Parameter

Parameters	Description
reference_id	Required: Yes Type: string Example: `reference_id=W4437KIWN0KDM13` The unique identifier associated with the created transaction.

Response Sample

{
    "status": true,
    "message": "Success",
    "result": {
        "data": {
            "facia_reference_id": "your_transaction's reference",
            "client_reference": "clients_reference",
            "face_search_response": {
                "result": {
                    "matched_faces": [
                        [
                            "65ae1ee3bb742faa2c0507we",
                            0.98,
                            "https://app.facia.ai/backend/api/get-proof/ZFV0dDVOTmpPV01mSGs5QThxZGNqdGhtbWhidmRiaG46NjVhZTFlZTNiYjc0MmZhYTJjMDUwN2Ki",
                            "qwerty2345fghj65fgfgh456"
                        ],
                        [
                            "65ae0ddc7adc1de48801b3ab",
                            0.98,
                            "https://app.facia.ai/backend/api/get-proof/TzVodnB3SnVvd3NGZ0xjU3E4MVVqdTd3S25kNnBlRjU6NjVhZTBkZGM3YWRjMWRlNDg4MDFiMzPi",
                            "qwerty2345fghj65fgfgh456"
                        ]
                    ],
                    "is_face_found": true
                }
            }
        }
    }
}

Response Parameter

Parameters	Description
facia_reference_id	Type: string Example: `facia_reference_id=QUSHZL1GQTQ8BZH` This key includes the reference number of the request.
client_reference	Type: string Example: `client_reference=QWERTY123456789` This is the client's provided reference ID associated with the transaction creation.
face_search_response	Type: object It contains the response generated by the system.
matched_faces	Type: Array This parameter returns the matched face images.
matched_faces[0][0]	Type: string ID of the uploaded proof against which the transaction was conducted.
matched_faces[0][1]	Type: string It represents the confidence score, indicating the degree of similarity between both objects.
matched_faces[0][2]	Type: string URL of the uploaded proof against which the transaction was conducted. It has expiry of 15 minutes.
matched_faces[0][3]	Type: string This is the client's request reference.
is_face_found	Type: boolean Indicates whether faces were found against the provided proof or not.

Face Search (1:N)

Create Face Search Transaction​

Endpoint

Authorization:​

Request Body Samples:​

Request Parameter​

Response Sample​

Response Parameter​

Face Search Result​

Endpoint

Authorization:​

Request Body Samples:​

Request Parameter​

Response Sample​

Response Parameter​

Create Face Search Transaction

Authorization:

Request Body Samples:

Request Parameter

Response Sample

Response Parameter

Face Search Result

Authorization:

Request Body Samples:

Request Parameter

Response Sample

Response Parameter