Face Search (One to Many)

Identify a person by searching a facial image against a database of enrolled identities. The service performs biometric face comparison and returns potential matching identities with similarity scores.

POST

/api/gw/services/face_search

---

Authorizations

x-api-key · string · required

API key used to authenticate the request.

---

Body

imageBase64 · string · required

Base64 encoded facial image to search against the identity database.

threshold · number

Minimum similarity score threshold for returning matches (0 to 1).

topK · number

Maximum number of matching identities to return.

---

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 search results.

data.matches · array

List of identities matching the submitted facial image.

data.matches[].identityId · string

Unique identifier of the matched identity.

data.matches[].similarityScore · number

Similarity score between the submitted face and matched identity (0 to 1).

data.matches[].confidence · number

Confidence score of the biometric match.

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 returned when face search processing fails.

---

Curl

curl -X POST "https://dev-idf-gw.cognetlabs.org/api/gw/services/face_search" \
-H "Content-Type: application/json" \
-d '{
  "imageBase64": "<base64-face-image>",
  "threshold": 0.85,
  "topK": 5
}'

import requests

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

payload = {
    "imageBase64": "<base64-face-image>",
    "threshold": 0.85,
    "topK": 5
}

res = requests.post(url, json=payload)
print(res.json())

fetch("https://dev-idf-gw.cognetlabs.org/api/gw/services/face_search", {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    imageBase64: "<base64-face-image>",
    threshold: 0.85,
    topK: 5
  })
})
.then(res => res.json())
.then(console.log);

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

$data = [
  "imageBase64" => "<base64-face-image>",
  "threshold" => 0.85,
  "topK" => 5
];

$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(`{
		"imageBase64":"<base64-face-image>",
		"threshold":0.85,
		"topK":5
	}`)

	req, _ := http.NewRequest(
		"POST",
		"https://dev-idf-gw.cognetlabs.org/api/gw/services/face_search",
		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 = "{\"imageBase64\":\"<base64-face-image>\", \"threshold\":0.85, \"topK\":5 }";

        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_search")
            .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_search")

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

payload = {
  imageBase64: "<base64-face-image>",
  threshold: 0.85,
  topK: 5
}

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": "8fa921c45",
  "correlationId": "58664e8f17d1452ea3b171e7a90e09bf",
  "data": {
    "matches": [
      {
        "identityId": "USER_10045",
        "similarityScore": 0.96,
        "confidence": 0.98
      }
    ]
  },
  "error": null,
  "durationMs": 420,
  "processedAt": "2026-04-29T13:59:35.9472104Z"
}

{
  "error": "ImageBase64 is required"
}