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": "data:image/png;base64,your_image_base64_here",
  "client_reference":"your_client_reference_here",
  "allow_override":0,
  "enroll_face":false
}

var myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer token");
myHeaders.append("Content-Type", "application/json");

var raw = JSON.stringify({
  "type": "face_search",
  "enroll_face": true,
  "file": "data:image/png;base64,your_image_base64_here",
  "client_reference": "your_client_reference_here",
  "allow_override": false
});

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

fetch("https://api.facia.ai/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": "data:image/png;base64,your_image_base64_here",
  "client_reference":"your_client_reference_here",
  "allow_override":false,
  "enroll_face": true
}'

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.facia.ai/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 => json_encode([
    'client_reference' => 'your_client_reference_here',
    'allow_override' => false,
    'enroll_face' => true,
    'file' => 'data:image/png;base64,your_image_base64_here'
  ]),
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Authorization: Bearer token'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import requests

url = "https://api.facia.ai/face-search"

payload = {
  'client_reference': 'your_client_reference_here',
  'allow_override': false,
  'enroll_face': True,
  'file': 'data:image/png;base64,your_image_base64_here'
}
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer token'
}

response = requests.post(url, headers=headers, json=payload)

print(response.text)

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

url = URI.parse('https://api.facia.ai/face-search')
token = 'your_token'
payload = {
  'client_reference' => 'your_client_reference_here',
  'allow_override' => false,
  'enroll_face'=>true,
  'file' => 'data:image/png;base64,your_image_base64_here'
}
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url.path)
request['Authorization'] = "Bearer #{token}"
request['Content-Type'] = 'application/json'
request.body = payload.to_json
response = http.request(request)
puts "Response Code: #{response.code}"
puts "Response Body: #{response.body}"

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

public class FaceSearchRequest {

    public static void main(String[] args) {
        try {
            String url = "https://api.facia.ai/face-search";
            String token = "your_token";
            String payload = "{"
                + "\"client_reference\": \"your_client_reference_here\","
                + "\"allow_override\": false,"
                + "\"enroll_face\": false,"
                + "\"file\": \"data:image/png;base64,your_image_base64_here\""
                + "}";
            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", "application/json");
            try (OutputStream outputStream = connection.getOutputStream()) {
                byte[] input = payload.getBytes(StandardCharsets.UTF_8);
                outputStream.write(input, 0, input.length);
            }
            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.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        string apiUrl = "https://api.facia.ai/face-search";
        string token = "your_token";
        var json = "{\"client_reference\":\"your_client_reference_here\",\"allow_override\":false,\"enroll_face\":false,\"file\":\"data:image/png;base64,your_image_base64_here\"}";
        var payload = new StringContent(json, Encoding.UTF8, "application/json");
        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"
    "net/http"
)

func main() {
    apiURL := "https://api.facia.ai/face-search"
    token := "your_token"
    payload := bytes.NewBuffer([]byte(`{
        "client_reference": "your_client_reference_here",
        "allow_override": false,
        "enroll_face": false,
        "file": "data:image/png;base64,your_image_base64_here"
    }`))

    request, err := http.NewRequest("POST", apiURL, payload)
    if err != nil {
        fmt.Println("Error creating request:", err)
        return
    }
    request.Header.Set("Content-Type", "application/json")
    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 (if `liveness` or `face_match` in services) Type: file or string multipart/form-data: the image file (.jpg, .jpeg, .png). application/json: a Base64 data URI including the prefix, e.g. `data:image/jpeg;base64,/9j/4AAQ...`. Plain Base64 without the `data:image/...;base64,` prefix is rejected. The face to be searched.
client_reference	Required: No Type: string Minimum: 5 characters Maximum: 255 characters Example: `client_reference="your_client_reference_here"` Required if allow_override field set to 1.
allow_override	Required: No Type: boolean Accepted values: `1` / `0` (or `true` / `false` in JSON requests) Default: `0` Set to `1` to replace the latest previously enrolled image with the new one for the given `client_reference`. `client_reference` is required when this is set to `1`.
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.

Multipart Upload Sample

Image fields can also be sent as files with multipart/form-data instead of Base64 JSON:

curl -X POST https://api.facia.ai/face-search \
  -H "Authorization: Bearer <token>" \
  -F "type=face_search" \
  -F "file=@/path/to/photo.jpg"

Response Sample

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

Response Parameter

Parameters	Description
reference_id	Type: string Example: `reference_id=your_reference_id_here` 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": "your_reference_id_here"
}

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

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

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": "your_reference_id_here"
}'

<?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=your_reference_id_here` The unique identifier associated with the created transaction.

Response Sample

{
    "status": true,
    "message": "success",
    "result": {
        "data": {
            "facia_reference_id": "your_reference_id_here",
            "client_reference": "your_client_reference_here",
            "face_search_response": {
                "result": {
                    "matched_faces": [
                        [
                            "65ae1ee3bb742faa2c0507we",
                            0.98,
                            "https://api.facia.ai/get-proof/ZFV0dDVOTmpPV01mSGs5QThxZGNqdGhtbWhidmRiaG46NjVhZTFlZTNiYjc0MmZhYTJjMDUwN2Ki",
                            "your_client_reference_here"
                        ],
                        [
                            "65ae0ddc7adc1de48801b3ab",
                            0.98,
                            "https://api.facia.ai/get-proof/TzVodnB3SnVvd3NGZ0xjU3E4MVVqdTd3S25kNnBlRjU6NjVhZTBkZGM3YWRjMWRlNDg4MDFiMzPi",
                            "your_client_reference_here"
                        ]
                    ],
                    "is_face_found": true
                }
            }
        }
    }
}

Response Parameter

Parameters	Description
facia_reference_id	Type: string Example: `facia_reference_id=your_reference_id_here` This key includes the reference number of the request.
client_reference	Type: string Example: `client_reference=your_client_reference_here` 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: number It is a floating number between 0 and 1, which 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​

Multipart Upload Sample​

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

Multipart Upload Sample

Response Sample

Response Parameter

Face Search Result

Authorization:

Request Body Samples:

Request Parameter

Response Sample

Response Parameter