> ## 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 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.

<div
  style={{
display: "inline-flex",
alignItems: "center",
background: "#fff",
borderRadius: "12px",
padding: "16px 24px",
border: "1px solid #e5e7eb",
boxShadow: "0 1px 3px rgba(0,0,0,0.05)",
fontFamily: "monospace",
gap: "16px"
}}
>
  <span
    style={{
color: "#2563eb",
fontWeight: "700",
fontSize: "18px",
letterSpacing: "0.5px"
}}
  >
    POST
  </span>

  <span
    style={{
fontSize: "14px",
color: "#4b5563"
}}
  >
    /api/gw/services/face\_match
  </span>
</div>

***

### Authorizations

<ResponseField name="x-api-key" type="string" required>
  API key used to authenticate the request.
</ResponseField>

***

### Body

<ResponseField name="faceImage1Base64" type="string" required>
  Base64-encoded first face image (selfie or document portrait).
</ResponseField>

<ResponseField name="faceImage2Base64" type="string" required>
  Base64-encoded second face image for comparison.
</ResponseField>

<ResponseField name="faceImage1FileName" type="string">
  Original filename of first image.
</ResponseField>

<ResponseField name="faceImage2FileName" type="string">
  Original filename of second image.
</ResponseField>

***

### Response

<Tabs>
  <Tab title="200">
    <ResponseField name="success" type="boolean">
      Indicates whether the request was processed successfully.
    </ResponseField>

    <ResponseField name="requestId" type="string">
      Unique identifier for the API request.
    </ResponseField>

    <ResponseField name="correlationId" type="string">
      Identifier used for tracing the request across systems.
    </ResponseField>

    <ResponseField name="data" type="object">
      Contains face matching results.
    </ResponseField>

    <ResponseField name="data.matchScore" type="number">
      Similarity score between the two faces (0 to 1).
    </ResponseField>

    <ResponseField name="data.matchResult" type="string">
      Result of the face comparison (e.g., MATCH, NO\_MATCH).
    </ResponseField>

    <ResponseField name="data.isMatch" type="boolean">
      Indicates whether both faces belong to the same person.
    </ResponseField>

    <ResponseField name="error" type="object | null">
      Contains error details if the request fails; otherwise null.
    </ResponseField>

    <ResponseField name="durationMs" type="number">
      Time taken to process the request in milliseconds.
    </ResponseField>

    <ResponseField name="processedAt" type="string">
      Timestamp when the request was processed (ISO 8601 format).
    </ResponseField>
  </Tab>

  <Tab title="400">
    <ResponseField name="error" type="string">
      Error message describing why the request failed.
    </ResponseField>

    <ResponseField name="code" type="string">
      Machine-readable error code for debugging.
    </ResponseField>
  </Tab>
</Tabs>

***

<RequestExample>
  ```bash Curl theme={null}
  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"
    }'
  ```

  ```python Python theme={null}
  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())
  ```

  ```javascript JavaScript theme={null}
  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 PHP theme={null}
  <?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;
  ?>
  ```

  ```go Go theme={null}
  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)
  }
  ```

  ```java Java theme={null}
  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());
      }
  }
  ```

  ```ruby Ruby theme={null}
  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
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
  "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"
  }
  ```

  ```json 400 theme={null}
  {
    "error": "FaceImage1Base64 and FaceImage2Base64 are required"
  }
  ```
</ResponseExample>