Face Match

Compare two facial images and return a biometric similarity score for identity verification and fraud prevention.
This service is typically used to match a selfie against a document portrait or verify if two images belong to the same individual.

POST

/api/gw/services/face_match

---

Authorizations

x-api-key · string · required

API key used to authenticate the request.

---

Body

faceImage1Base64 · string · required

Base64-encoded first face image (selfie or document portrait).

faceImage2Base64 · string · required

Base64-encoded second face image for comparison.

faceImage1FileName · string

Original filename of first image.

faceImage2FileName · string

Original filename of second image.

---

Response

200

success · boolean

Indicates whether the request was processed successfully.

requestId · string

Unique identifier for the API request.

correlationId · string

Identifier used for tracing the request across systems.

data · object

Contains face matching results.

data.matchScore · number

Similarity score between the two faces (0 to 1).

data.matchResult · string

Result of the face comparison (e.g., MATCH, NO_MATCH).

data.isMatch · boolean

Indicates whether both faces belong to the same person.

error · object | null

Contains error details if the request fails; otherwise null.

durationMs · number

Time taken to process the request in milliseconds.

processedAt · string

Timestamp when the request was processed (ISO 8601 format).

400

error · string

Error message describing why the request failed.

code · string

Machine-readable error code for debugging.

---

Curl

curl -X POST "https://dev-idf-gw.cognetlabs.org/api/gw/services/face-match" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "faceImage1Base64": "<base64-face-1>",
    "faceImage2Base64": "<base64-face-2>",
    "faceImage1FileName": "face1.jpg",
    "faceImage2FileName": "face2.jpg"
  }'

import requests

url = "https://dev-idf-gw.cognetlabs.org/api/gw/services/face-match"

headers = {
    "Content-Type": "application/json",
    "x-api-key": "YOUR_API_KEY"
}

payload = {
    "faceImage1Base64": "<base64-face-1>",
    "faceImage2Base64": "<base64-face-2>",
    "faceImage1FileName": "face1.jpg",
    "faceImage2FileName": "face2.jpg"
}

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

fetch("https://dev-idf-gw.cognetlabs.org/api/gw/services/face-match", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "YOUR_API_KEY"
  },
  body: JSON.stringify({
    faceImage1Base64: "<base64-face-1>",
    faceImage2Base64: "<base64-face-2>",
    faceImage1FileName: "face1.jpg",
    faceImage2FileName: "face2.jpg"
  })
})
.then(res => res.json())
.then(console.log);

<?php
$url = "https://dev-idf-gw.cognetlabs.org/api/gw/services/face-match";

$data = [
  "faceImage1Base64" => "<base64-face-1>",
  "faceImage2Base64" => "<base64-face-2>",
  "faceImage1FileName" => "face1.jpg",
  "faceImage2FileName" => "face2.jpg"
];

$options = [
  "http" => [
    "header"  => "Content-Type: application/json\r\nx-api-key: YOUR_API_KEY",
    "method"  => "POST",
    "content" => json_encode($data),
  ],
];

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

echo $result;
?>

package main

import (
	"bytes"
	"net/http"
)

func main() {
	jsonData := []byte(`{
		"faceImage1Base64":"<base64-face-1>",
		"faceImage2Base64":"<base64-face-2>"
	}`)

	req, _ := http.NewRequest("POST",
		"https://dev-idf-gw.cognetlabs.org/api/gw/services/face-match",
		bytes.NewBuffer(jsonData),
	)

	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("x-api-key", "YOUR_API_KEY")

	client := &http.Client{}
	client.Do(req)
}

import okhttp3.*;

public class Main {
    public static void main(String[] args) throws Exception {

        OkHttpClient client = new OkHttpClient();

        String json = "{\"faceImage1Base64\":\"<base64-face-1>\", \"faceImage2Base64\":\"<base64-face-2>\" }";

        RequestBody body = RequestBody.create(
            json, MediaType.parse("application/json")
        );

        Request request = new Request.Builder()
            .url("https://dev-idf-gw.cognetlabs.org/api/gw/services/face-match")
            .addHeader("x-api-key", "YOUR_API_KEY")
            .post(body)
            .build();

        Response response = client.newCall(request).execute();
        System.out.println(response.body().string());
    }
}

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

uri = URI.parse("https://dev-idf-gw.cognetlabs.org/api/gw/services/face-match")

header = {
  'Content-Type': 'application/json',
  'x-api-key': 'YOUR_API_KEY'
}

payload = {
  faceImage1Base64: "<base64-face-1>",
  faceImage2Base64: "<base64-face-2>"
}

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

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

200

{
"success":true,
"requestId":"3b3dd30428e4",
"correlationId":"corr-1777440469940",
"data":{
"matchScore":0.9692000000000001,
"matchResult":"MATCH",
"isMatch":true
},
"error":null,
"durationMs":3858,
"processedAt":"2026-04-29T05:27:54.3670847Z"
}

{
  "error": "FaceImage1Base64 and FaceImage2Base64 are required"
}