> ## Documentation Index
> Fetch the complete documentation index at: https://venator-06aff335.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 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
API key used to authenticate the request.
***
### Body
Base64 encoded facial image to search against the identity database.
Minimum similarity score threshold for returning matches (0 to 1).
Maximum number of matching identities to return.
***
### Response
Indicates whether the request was processed successfully.
Unique identifier for the API request.
Identifier used for tracing the request across systems.
Contains face search results.
List of identities matching the submitted facial image.
Unique identifier of the matched identity.
Similarity score between the submitted face and matched identity (0 to 1).
Confidence score of the biometric match.
Contains error details if the request fails; otherwise null.
Time taken to process the request in milliseconds.
Timestamp when the request was processed (ISO 8601 format).
Error message returned when face search processing fails.
***
```bash Curl theme={null}
curl -X POST "https://dev-idf-gw.cognetlabs.org/api/gw/services/face_search" \
-H "Content-Type: application/json" \
-d '{
"imageBase64": "",
"threshold": 0.85,
"topK": 5
}'
```
```python Python theme={null}
import requests
url = "https://dev-idf-gw.cognetlabs.org/api/gw/services/face_search"
payload = {
"imageBase64": "",
"threshold": 0.85,
"topK": 5
}
res = requests.post(url, json=payload)
print(res.json())
```
```javascript JavaScript theme={null}
fetch("https://dev-idf-gw.cognetlabs.org/api/gw/services/face_search", {
method: "POST",
headers: {
"Content-Type": "application/json"
},
body: JSON.stringify({
imageBase64: "",
threshold: 0.85,
topK: 5
})
})
.then(res => res.json())
.then(console.log);
```
```php PHP theme={null}
"",
"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;
?>
```
```go Go theme={null}
package main
import (
"bytes"
"net/http"
)
func main() {
jsonData := []byte(`{
"imageBase64":"",
"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)
}
```
```java Java theme={null}
import okhttp3.*;
public class Main {
public static void main(String[] args) throws Exception {
OkHttpClient client = new OkHttpClient();
String json = "{\"imageBase64\":\"\", \"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());
}
}
```
```ruby Ruby theme={null}
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: "",
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
```
```json 200 theme={null}
{
"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"
}
```
```json 400 theme={null}
{
"error": "ImageBase64 is required"
}
```