SmartEnroll API コンパニオン

ユーザーがホスト型 SmartEnroll KYC を完了したあと、バックエンドへ結果を取り込むためのガイドです。顔照合スコア、ライブネス、Webhook、重要なエンドポイントを扱います。製品ドキュメントの補助であり、セルフホスト SmartEnroll API の置き換えではありません。

フロー概要

flowchart LR
  hosted[Hosted_SmartEnroll]
  compare[Face_compare]
  webhook[Webhook_face_verification_compare]
  getAR[GET_app_registrations_populate]
  hosted --> compare
  compare --> webhook
  compare --> getAR
  getAR --> scores[score_passed_threshold]

エンドユーザーがホスト型フローで書類＋生体ステップを完了します。
Verifik がプロジェクトのしきい値で顔照合（セルフィー vs 書類の顔）を実行します。
Webhook（設定時）を受け取るか、populates 付きで app registration を取得します。
score、passed、compare_min_score でビジネスルールを適用します。

顔照合スコアの読み方

公開の GET /v2/face-verifications/:id はありません。スコアは app registration に紐づく FaceVerification にあります。

GET https://api.verifik.co/v2/app-registrations/{id}?populates[]=compareFaceVerification

populate 後の主なフィールド:

フィールド	意味
`compareFaceVerification.result.score`	類似度スコア（0–1）
`compareFaceVerification.result.passed`	有効なしきい値を満たしたか
`compareFaceVerification.result.compare_min_score`	その照合で使われたしきい値
`compareFaceVerification.comparedAt`	照合実行時刻

TTL: FaceVerification は本番で約 90 日（開発 10 日）で期限切れになります。期限後は app registration が残っていても compareFaceVerification が空になることがあります。

参照: Get App Registration。

便利な populates

エンロール全体のスナップショットによく使うセット:

project, projectFlow, emailValidation, phoneValidation, biometricValidation, documentValidation, person, face, documentFace, compareFaceVerification, informationValidation

主要エンドポイント

エンドポイント	用途
`POST /v2/face-recognition/liveness`	標準ライブネス検出
`POST /v2/face-recognition/liveness-score`	スコア中心のライブネス（課金は `/liveness` と同じ）
`POST /v2/face-recognition/compare`	1:1 顔照合（直接 API）
`POST /v2/face-recognition/compare-with-liveness`	照合のあとライブネス（順次）
`POST /v2/face-recognition/compare/app-registration`	ホスト経路の照合: セッションの `appRegistrationId`、保存済み顔を gallery/probe に使用、空 body `{}` 可、しきい値は project flow
`GET /v2/app-registrations/:id`	エンロール取得＋スコアの populate
`POST /v2/biometric-validations/app-registration`	ホストセッションの生体／ライブネス手順
`POST /v2/document-validations/app-registration`	ホストセッションの書類キャプチャ／検証
`POST /v2/identity-images/appRegistration`	本人確認画像の保存（`face`、`documentFace` など）

完全カスタム UI は SmartEnroll Self Hosted から。

顔照合のしきい値

コンテキスト	値
ホスト型 SmartEnroll / project flow の既定	`0.85`（`compareMinScore`）
直接 face-recognition API（`compare_min_score`）	`0.67`–`0.95`（省略時は `0.85`）

印刷された書類写真（例: コロンビアの CC）は、ライブ同士より低いスコアになりがちです。正当なユーザーが 0.7 台で失敗する場合は、誤受理リスクを検証したうえでプロジェクトしきい値の引き下げを検討してください。

`cropFace`

face-recognition compare エンドポイントではサーバー側 cropFace は非対応です。フィールドは省略してください（送っても無視されます）。顔中心の画像を送るか、クライアント側で切り抜いてから呼び出してください。

Webhooks

project flow に Webhook がある場合、顔照合は接尾辞 face_verification_compare のイベントを送信します。配信される type は次のとおりです。

{projectFlow.type}_face_verification_compare

例: onboarding_face_verification_compare。

ペイロードには app registration のフィールドと compareResult が含まれます。一覧: Smart Enroll KYC Webhooks。

ライブネス / PAD（製品要約）

Verifik の顔ライブネスは、プレゼンテーション攻撃検知（PAD）付きの生体スタックを使用します。ライブネスは iBeta Level 2 認定で、ISO 30107 Level 1 / Level 2 に整合します。印刷写真、動画リプレイ、3D マスクなどの一般的ななりすましを、単一画像チェックで検知するよう設計されています。詳細: Liveness、Liveness Score。

クイックレシピ

ホスト型エンロールの完了を待つ（または完了させる）。
{type}_face_verification_compare を受信するか、GET /v2/app-registrations/{id}?populates[]=compareFaceVerification を呼ぶ。
result.score、result.passed、result.compare_min_score を読む。
承認／レビュー／却下ルールを適用する（FaceVerification の TTL に注意）。

フロー概要​

顔照合スコアの読み方​

便利な populates​

主要エンドポイント​

顔照合のしきい値​

cropFace​

Webhooks​

ライブネス / PAD（製品要約）​

関連する製品ドキュメント​

クイックレシピ​