> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.withverifa.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.withverifa.com/_mcp/server.

# Find cross-session image similarity matches

GET https://api.withverifa.com/api/v1/identities/{identity_id}/image-matches

Compares face embeddings stored for the given identity against all other
embeddings in the organization. Returns identities with similar selfies or
document photos, ranked by similarity score.

This endpoint detects reused photos and documents across sessions — a key
signal for synthetic identity fraud, document reuse, and fraud rings.

Results are deduplicated by identity (keeping the highest similarity score
when multiple embeddings match). Only matches above the specified threshold
are returned.


Reference: https://docs.withverifa.com/api-reference/identities/get-image-matches

## Authentication

- `X-API-Key` header (required) — Organization API key. Keys are prefixed with `vk_live_` (production) or `vk_sandbox_` (sandbox).

## Request

### Path parameters

- `identity_id` (string, required) — Identity ID (`idn_*`) or external reference.

### Query parameters

- `threshold` (double, optional) — Minimum cosine similarity score (0.1–1.0) to count as a match. Default `0.6` balances precision vs recall. Use `0.8` for high-confidence matches only; use `0.4` for broader search with more false positives.
- `source_type` (enum, optional) — Filter by embedding source type. `selfie` matches selfie-to-selfie; `document_front` matches ID photo-to-ID photo. If omitted, all source types are compared.
  - Allowed values: `selfie`, `document_front`
- `limit` (integer, optional, default: 20) — Maximum number of matches to return.
- `offset` (integer, optional, default: 0) — Offset for pagination.

### Headers

- `Verifa-Version` (date, optional) — API version date string (e.g. `2026-02-01`). If omitted, the version pinned to your API key is used.
- `Key-Inflection` (enum, optional, default: snake) — Response key casing. Defaults to `snake`.
  - Allowed values: `camel`, `kebab`, `snake`

## Response

### 200

Paginated list of image similarity matches.

- `data` (list of ApiV1IdentitiesIdentityIdImageMatchesGetResponsesContentApplicationJsonSchemaDataItems, required)
- `pagination` (ApiV1IdentitiesIdentityIdImageMatchesGetResponsesContentApplicationJsonSchemaPagination, required)

## Errors

### 401 Unauthorized Error

Missing or invalid API key.

- `error` (string, required) — Short error code.
- `status_code` (integer, required) — HTTP status code.
- `detail` (string, optional) — Human-readable error description.

### 404 Not Found Error

Resource not found.

- `error` (string, required) — Short error code.
- `status_code` (integer, required) — HTTP status code.
- `detail` (string, optional) — Human-readable error description.

## Types

### ApiV1IdentitiesIdentityIdImageMatchesGetResponsesContentApplicationJsonSchemaDataItems

- `identity_id` (string, required) — Identity ID of the matched face.
- `session_id` (string, required) — Session where the matched embedding was captured.
- `similarity_score` (double, required) — Cosine similarity between face embeddings (0–1). Higher = more similar. Scores above 0.8 indicate very high confidence of the same person or reused photo.
- `matched_at` (datetime, required) — When the matched embedding was created.
- `embedding_id` (string, required) — ID of the matched face embedding record.

### ApiV1IdentitiesIdentityIdImageMatchesGetResponsesContentApplicationJsonSchemaPagination

- `total` (integer, required) — Total number of matching items.
- `limit` (integer, required)
- `offset` (integer, required)

## Examples

**Response**

```json
{
  "data": [
    {
      "identity_id": "idn_def456",
      "session_id": "ses_xyz789",
      "similarity_score": 0.8234,
      "matched_at": "2026-03-01T12:00:00Z",
      "embedding_id": "facemb_abc123"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 1,
    "offset": 1
  }
}
```

**SDK Code**

```python
import requests

url = "https://api.withverifa.com/api/v1/identities/identity_id/image-matches"

headers = {"X-API-Key": "<apiKey>"}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.withverifa.com/api/v1/identities/identity_id/image-matches';
const options = {method: 'GET', headers: {'X-API-Key': '<apiKey>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

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

func main() {

	url := "https://api.withverifa.com/api/v1/identities/identity_id/image-matches"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<apiKey>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.withverifa.com/api/v1/identities/identity_id/image-matches")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<apiKey>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.withverifa.com/api/v1/identities/identity_id/image-matches")
  .header("X-API-Key", "<apiKey>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.withverifa.com/api/v1/identities/identity_id/image-matches', [
  'headers' => [
    'X-API-Key' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.withverifa.com/api/v1/identities/identity_id/image-matches");
var request = new RestRequest(Method.GET);
request.AddHeader("X-API-Key", "<apiKey>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["X-API-Key": "<apiKey>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.withverifa.com/api/v1/identities/identity_id/image-matches")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```