---
title: "Face Match v2"
method: POST
path: "/v2/verify/face_match"
tags: ["Face Match v2"]
---

# Face Match v2

`POST /v2/verify/face_match`

Compares two face images and returns a match verdict with a similarity score and confidence band. The primary image (`image1`) is uploaded as a file. The comparison image may be supplied either as an uploaded file (`image2`) or as an HTTPS URL (`image2_url`). A non-matching pair still completes successfully (`status: "success"`) with `is_match: false`.

**Response contract:** Every completed verification returns HTTP 200. A successful result returns `status: "success"` with `error_code: null` and a populated `data` object. A valid request with no matching record (or a business rejection) also returns HTTP 200 with `status: "failed"`, a non-null `error_code`, and `data: null`. Do not treat HTTP 200 alone as success — always branch on `status` and inspect `error_code`. Authenticate with your `X-Client-ID` and `X-API-KEY` headers. Transport, auth, and validation problems use standard 4xx/5xx status codes.

## Response `200`

Face match completed. `data.is_match` carries the verdict.

- FaceMatchResponse
  - `status` string, required
  - `message` string, nullable
  - `error_code` string, nullable
  - `data` FaceMatchData
    - `is_match` boolean, nullable
    - `match_score` number, nullable
    - `confidence` string, nullable
    - `extras` object, nullable
  - `tranx_id` string, nullable
  - `timestamp` string, nullable

## Other responses

- `400` — Invalid input — malformed request or missing required fields.
- `401` — Missing or invalid authentication credentials (X-Client-ID / X-API-KEY).
- `422` — Request body failed schema validation.
- `429` — Too many requests — rate limited (IDTO_006). Retry after a short wait.
- `500` — Internal server error.
- `503` — Vendor temporarily unavailable — verification could not be completed (IDTO_008). Retry shortly.

---

[API](https://skmtc.net/idto/apis/verification-api.md) · [All operations](https://skmtc.net/idto/apis/verification-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/idto/verification-api/versions/e3d57dab8db4/schema)