顔照合レポート：類似度スコアのJSON

概要

顔照合レポートは、ライブネス検知中に撮影されたライブセルフィーと参照画像（多くの場合、身分証明書から抽出された顔写真）との1:1の生体比較を記録します。0–100の単一の類似度スコア、比較した2枚の画像の署名付きURL、参照画像の取得元セッション、照合で発生した警告を返します。このレポートは、ユーザーがワークフロー内のライブネスステップと書類ステップの両方を完了した後（生体認証など顔写真ベースのワークフローでは、ライブネスのみの完了後）に生成されます。任意の2つの顔画像を自分で指定する場合は、スタンドアロンの顔照合APIから直接生成されます。各レポートには、セッション全体のステータスとは独立した独自のstatusがあり、顔照合ステップ単体がどのように判定されたかを示します。

承認済み：scoreがレビューしきい値を上回り、自動却下の警告が発生していない。
レビュー中：scoreが却下しきい値とレビューしきい値の間にある、またはスコアを算出できずface_match_not_computed_actionがREVIEWである。
却下：scoreが却下しきい値以下である、NO_REFERENCE_IMAGEが発生した、またはスコアを算出できずface_match_not_computed_actionがDECLINEである。
Resub Requested：レビュアーがコンソールから、このステップの再提出をユーザーに要求した。
Not Finished：顔照合ステップがまだ結果を出していない（失敗した撮影をユーザーが再試行している間を含む）。

APIレスポンスでの表示場所

顔照合レポートはface_matches[]配列内に含まれます。常にJSON配列であり、単数形のface_matchオブジェクトになることはありません。少なくとも1つの顔照合ステップがデータを生成するまではnullで、ワークフローで顔照合が複数回実行されると複数のエントリが含まれます。Adaptive Age Verificationワークフローでも、本人確認のフォールバックが実行されるとこの配列にデータが入ります。このワークフローには独自の顔照合ノードがないため、そのエントリのnode_idには年齢推定ノードのIDが設定されます。

セッション判定API：GET /v3/session/{sessionId}/decision/はトップレベルでface_matches[]を返します。セッション判定の取得を参照してください。
Webhook：ステップがデータを生成すると、session.status.updatedペイロードに同じface_matches[]配列が含まれます。Webhookを参照してください。
スタンドアロン顔照合API：直接の1:1比較については、顔照合スタンドアロンAPIを参照してください。

response.face_matches[0]を読み取り、配列を反復処理してください。古いチュートリアルの一部で参照されていた単数形のface_matchの形式は、v3の判定エンドポイントには存在しません。

スキーマ

フィールドごとの正式なスキーマはデータモデルリファレンスページにあります。以下のフィールドはその正式なスキーマに準拠しています。

フィールド	型	説明
`status`	`"Approved" \| "Declined" \| "In Review" \| "Resub Requested" \| "Not Finished"`	顔照合ステップのステータス（`FeatureStatusChoices`）。
`node_id`	string \| null	このレポートを生成したワークフローグラフのノード。
`score`	number 0–100 \| null	生体類似度スコア（小数点以下2桁に丸め）。比較できなかった場合は`null`。
`source_image_session_id`	string \| null	参照（ソース）画像として使われた保存済み顔写真を持つセッションのUUID。顔写真ベースのフロー（生体認証、またはセッション作成時に顔写真を指定した場合）で設定されます。参照画像が同じセッションで撮影された書類の顔写真である場合は`null`。
`source_image`	string（署名付きURL）	参照画像（通常は書類の顔写真）。有効期間の短い署名付きURLです。速やかにダウンロードし、URL自体は決して保存しないでください。
`target_image`	string（署名付きURL）	対象画像（通常はライブネスのセルフィー）。有効期間の短い署名付きURLです。速やかにダウンロードし、URL自体は決して保存しないでください。
`warnings[]`	array	モジュールレベルの警告。各エントリには`feature`（常に`"FACEMATCH"`）、`risk`、`additional_data`、`log_type`、`short_description`、`long_description`、`node_id`が含まれます。顔照合の警告を参照してください。

ステータス値

ステータス	意味	後続への影響
`Approved`	スコアがレビューしきい値を上回り、自動却下の警告が発生していない。	顔照合の成功として扱われます。
`In Review`	スコアが却下しきい値を上回りレビューしきい値以下である、またはスコアを算出できず（`FACE_MATCH_NOT_COMPUTED`。例：書類以外の照会で参照画像が残らなかった場合）、`face_match_not_computed_action`が`REVIEW`に設定されている。	レビュアーが対応するまで、セッションも`In Review`に移行します。
`Declined`	スコアが却下しきい値以下である、`NO_REFERENCE_IMAGE`が発生した、またはスコアを算出できず`face_match_not_computed_action`が`DECLINE`に設定されている。	別の承認済み分岐がワークフローの条件を満たす場合を除き、セッションは却下されます。
`Resub Requested`	レビュアーがコンソールからこのステップの再提出を要求した。	ユーザーに再撮影が求められます。
`Not Finished`	顔照合ステップが結果を出していない（入力が不足していた、ワークフローが比較ステップに到達しなかった、またはユーザーがまだ撮影の再試行ループ中である）。	分岐は完了していません。

類似度が低く失敗した場合は、ステータスが確定する前に再試行が行われます。ユーザーは最大face_match_max_attempts回（デフォルトは3回）撮影でき、最後の試行のスコアのみが適用されます。ワークフローノードで設定したカスタムステータスルールにより、結果のステータスをさらに調整できます。その場合、スコアから導かれたステータスとDeclined > In Review > Approvedの優先順位で組み合わされます。

例

承認済み (明確な一致)

{
  "face_matches": [
    {
      "status": "Approved",
      "node_id": "feature_face_match_1",
      "score": 96.42,
      "source_image_session_id": null,
      "source_image": "https://<media-host>/source-image.jpg",
      "target_image": "https://<media-host>/target-image.jpg",
      "warnings": []
    }
  ]
}

レビュー中 (境界線上の類似度)

{
  "face_matches": [
    {
      "status": "In Review",
      "node_id": "feature_face_match_1",
      "score": 65.43,
      "source_image_session_id": null,
      "source_image": "https://<media-host>/source-image.jpg",
      "target_image": "https://<media-host>/target-image.jpg",
      "warnings": [
        {
          "feature": "FACEMATCH",
          "risk": "LOW_FACE_MATCH_SIMILARITY",
          "additional_data": null,
          "log_type": "warning",
          "short_description": "Low face match similarity",
          "long_description": "The facial features of the provided image don't closely match the reference image, suggesting a potential identity mismatch.",
          "node_id": "feature_face_match_1"
        }
      ]
    }
  ]
}

却下 (比較対象となる参照画像なし)

{
  "face_matches": [
    {
      "status": "Declined",
      "node_id": "feature_face_match_1",
      "score": null,
      "source_image_session_id": null,
      "source_image": null,
      "target_image": "https://<media-host>/target-image.jpg",
      "warnings": [
        {
          "feature": "FACEMATCH",
          "risk": "NO_REFERENCE_IMAGE",
          "additional_data": null,
          "log_type": "error",
          "short_description": "No source image found for performing face match",
          "long_description": "A reference image for facial comparison is missing, preventing the system from completing the face matching process.",
          "node_id": "feature_face_match_1"
        }
      ]
    }
  ]
}

セキュリティに関する注意

source_imageとtarget_imageの署名付きURLは生体データであり、短い有効期間が過ぎると失効します。有効期間の短いものとして扱い、キャッシュしたり公開したりしないでください。通常、アプリケーションに必要なのはstatusとscoreだけです。サーバー上の生体データを最小限に抑えるため、保存するデータはできるだけ少なくしてください。

認証

検証

モニタリング

プラットフォーム

顔照合レポート：類似度スコアのJSON

概要

APIレスポンスでの表示場所

スキーマ

ステータス値

例

承認済み (明確な一致)

レビュー中 (境界線上の類似度)

却下 (比較対象となる参照画像なし)

セキュリティに関する注意

関連情報

​概要

​APIレスポンスでの表示場所

​スキーマ

​ステータス値

​例

​承認済み (明確な一致)

​レビュー中 (境界線上の類似度)

​却下 (比較対象となる参照画像なし)

​セキュリティに関する注意

​関連情報

概要

APIレスポンスでの表示場所

スキーマ

ステータス値

例

承認済み (明確な一致)

レビュー中 (境界線上の類似度)

却下 (比較対象となる参照画像なし)

セキュリティに関する注意

関連情報