Face Match (1:1)

Within FACIA, the Face Match service takes center stage as a dynamic endpoint, propelling transaction requests into the realm of facial matching algorithms. This innovative algorithm meticulously evaluates the likeness between a Selfie (Photo) and either a Document or another Selfie (Photo), adopting a seamless 1:1 matching approach.

Create Face Match Transaction

This endpoint initiates a transaction request for the face match algorithm, serving as a 1:1 service. The endpoint accepts three fields in the request payload, as mentioned in the request parameters.

Endpoint

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

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 /face-match  HTTP/1.1
//Host:  https://api.facia.ai
//Content-Type: application/json
//client-secret: <your client_secret key>

{
  "type": "photo_id_match",
  "face_frame": "data:image/png;base64,your_image_base64_here",
  "id_frame": "data:image/png;base64,your_image_base64_here",
  "client_reference": "your_client_reference_here",
  "allow_override": 0,
  "enroll_face":true
}

Javascript

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

var raw = JSON.stringify({
  "type": "photo_id_match",
  "enroll_face": true,
  "face_frame": "data:image/png;base64,your_image_base64_here",
  "id_frame": "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-match", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Curl

curl --location 'https://api.facia.ai/face-match' \
--header 'Content-Type: application/json' \
--data '{
  "type": "photo_id_match",
  "face_frame": "data:image/png;base64,your_image_base64_here",
  "id_frame": "data:image/png;base64,your_image_base64_here",
  "client_reference":"your_client_reference_here",
  "allow_override":false,
  "enroll_face": true
}'

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.facia.ai/face-match',
  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,
    'face_frame' => 'data:image/png;base64,your_image_base64_here',
    'id_frame' => '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;

Python

import requests

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

payload = {
  'client_reference': 'your_client_reference_here',
  'allow_override': False,
  'enroll_face': False,
  'face_frame': 'data:image/png;base64,your_image_base64_here',
  'id_frame': '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)

Ruby

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

url = URI.parse('https://api.facia.ai/face-match')
token = 'adasfewadscxz'
payload = {
  client_reference: 'your_client_reference_here',
  allow_override: false,
  enroll_face: false,
  face_frame: 'data:image/png;base64,your_image_base64_here',
  id_frame: 'data:image/png;base64,your_image_base64_here'
}

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

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}"

Java

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

public class FaceMatchRequest {

    public static void main(String[] args) {
        try {
            String token = "your_token";
            URL url = new URL("https://api.facia.ai/face-match");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();
            conn.setRequestMethod("POST");
            conn.setRequestProperty("Content-Type", "application/json");
            conn.setRequestProperty("Authorization", "Bearer " + token);
            conn.setDoOutput(true);

            String payload = "{\"client_reference\": \"your_client_reference_here\",\"allow_override\": false,\"enroll_face\":true,\"face_frame\": \"data:image/png;base64,your_image_base64_here\",\"id_frame\": \"data:image/png;base64,your_image_base64_here\"}";
            try (OutputStream os = conn.getOutputStream()) {
                byte[] input = payload.getBytes("utf-8");
                os.write(input, 0, input.length);
            }

            System.out.println("Response Code: " + conn.getResponseCode());
            try (InputStream is = conn.getInputStream();
                 BufferedReader br = new BufferedReader(new InputStreamReader(is, "utf-8"))) {
                StringBuilder response = new StringBuilder();
                String responseLine;
                while ((responseLine = br.readLine()) != null) {
                    response.append(responseLine.trim());
                }
                System.out.println("Response Body: " + response.toString());
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

C#

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-match";
        string token = "your_token";
        string json = "{\"client_reference\":\"your_client_reference_here\",\"allow_override\":false,\"enroll_face\":false,\"face_frame\":\"data:image/png;base64,your_image_base64_here\",\"id_frame\":\"data:image/png;base64,your_image_base64_here\"}";
        using (var httpClient = new HttpClient())
        {
            httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
            var content = new StringContent(json, Encoding.UTF8, "application/json");
            var response = await httpClient.PostAsync(apiUrl, content);
            Console.WriteLine($"Response Code: {response.StatusCode}");
            string responseBody = await response.Content.ReadAsStringAsync();
            Console.WriteLine($"Response Body: {responseBody}");
        }
    }
}

Go

package main

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

func main() {
    apiURL := "https://api.facia.ai/face-match"
    token := "your_token"
    jsonStr := []byte(`{
        "client_reference": "your_client_reference_here",
        "allow_override": false,
        "enroll_face": false,
        "face_frame": "data:image/png;base64,your_image_base64_here",
        "id_frame": "data:image/png;base64,your_image_base64_here"
    }`)
    request, err := http.NewRequest("POST", apiURL, bytes.NewBuffer(jsonStr))
    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=photo_id_match The type must be "photo_id_match".
face_frame	Required: Yes 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 live face (selfie) image.
id_frame	Required: Yes 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 ID document image.
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-match \
  -H "Authorization: Bearer <token>" \
  -F "type=photo_id_match" \
  -F "face_frame=@/path/to/selfie.jpg" \
  -F "id_frame=@/path/to/id_card.jpg"

Response Sample

{
  "status": true,
  "message": "Transaction Created",
  "result": {
    "data": {
      "reference_id": "your_reference_id_here",
      "similarity_status": "1",
      "similarity_score": "0.98",
      "client_reference": "your_client_reference_here"
    }
  }
}

Response Parameter

Parameters	Description
reference_id	Type: string Example: reference_id=your_reference_id_here The unique identifier associated with the created transaction.
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 Indicates the calculated similarity score of the images provided.
client_reference	Type: string Example: client_reference=your_client_reference_here Contains the unique ID defined for the end user.