`Verification.Result`

確認試行の結果とともに発行されます。

フィールド

フィールド	タイプ	必須	説明
`eventType`	string	はい	常に`"Verification.Result"`
`data`	object	はい	確認結果データ
`data.id`	string (UUID)	はい	一意の確認ID
`data.status`	string	はい	`PASS`または`FAIL`のいずれか
`data.ageCategory`	string	いいえ	推定年齢カテゴリ。`adult`、`digital-youth`、または`digital-minor`のいずれか。`status`が`PASS`で`age`が存在する場合にのみ存在します
`data.method`	string	いいえ	使用された確認方法。`PASS`ステータスの場合は常に存在します。`FAIL`ステータスの場合、`failureReason`が`age-criteria-not-met`の場合にのみ存在します
`data.failureReason`	string	いいえ	確認が失敗した理由。`status`が`FAIL`の場合は常に存在します。`age-criteria-not-met`、`max-attempts-exceeded`、または`fraudulent-activity-detected`のいずれかです
`data.age`	object	いいえ	年齢の詳細。`age.low`と`age.high`の両方が利用可能な場合に存在します。`FAIL`ステータスの場合、`failureReason`が`age-criteria-not-met`の場合にのみ存在します
`data.age.low`	number	いいえ	推定年齢の下限。ID文書チェックなどのハード年齢確認方法の場合、これは正確な年齢です
`data.age.high`	number	いいえ	推定年齢の上限。ID文書チェックなどのハード年齢確認方法の場合、これは正確な年齢です
`data.dob`	string (YYYY-MM-DD)	いいえ	確認された生年月日。確認方法が提供する場合にのみ含まれます。方法から利用可能な場合は常に含まれます

例

PASS
FAIL (確定)
FAIL (不確定)

{
  "eventType": "Verification.Result",
  "data": {
    "id": "4e57301e-a4d1-498f-ac3f-f3d4de19abf6",
    "status": "PASS",
    "method": "id-document",
    "age": {
      "low": 43,
      "high": 43
    },
    "dob": "1981-06-20"
  }
}

{
  "eventType": "Verification.Result",
  "data": {
    "id": "fe10accb-b845-4fc8-ac44-6130b7e0b8bd",
    "status": "FAIL",
    "method": "age-estimation-scan",
    "age": {
      "low": 13,
      "high": 17
    },
    "failureReason": "age-criteria-not-met"
  }
}

{
  "eventType": "Verification.Result",
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174002",
    "status": "FAIL",
    "failureReason": "max-attempts-exceeded"
  }
}

検証イベントコントラクト

概要

このセクションは、2つのメカニズムを通じて提供される検証ステータスのAPIコントラクトを定義します：

Webhookイベント: 検証が完了したときに送信されるVerification.Result Webhookイベント
APIエンドポイント: 検証ステータスをポーリングするためのGET /age-verification/get-statusエンドポイント

このコントラクトは、すべての可能な結果タイプのフィールド存在ルール、データ型、および解釈ガイダンスを指定します。両方のメカニズムは類似のデータを提供しますが、ステータス値、フィールドの存在、および構造に重要な違いがあることに注意する必要があります。

DOMメッセージは信頼できる情報源ではありません

検証結果は、UI制御の目的でDOMメッセージを介してフロントエンドアプリケーションにも伝達されます。ただし、統合ロジックでは、webhookイベントとGET /age-verification/get-statusエンドポイントの応答のみを信頼できる権威あるデータソースとして考慮する必要があります。DOMメッセージは、フロントエンドアプリケーションの状態管理のみを目的として提供され、重要なビジネス決定やデータ永続化の基礎として使用すべきではありません。

データ構造

Webhookイベント構造

Webhookイベントはイベントエンベロープでラップされます：

{
  "eventType": "Verification.Result",
  "data": {
    "id": "uuid",
    "status": "PASS" | "FAIL",
    "ageCategory": "adult" | "digital-youth" | "digital-minor" | null,
    "method": "id-document" | "credit-card" | "self-confirmation" | "social-security-number" | "email-confirmation" | "age-estimation-scan" | null,
    "age": {
      "low": number,
      "high": number
    } | null,
    "dob": "YYYY-MM-DD" | null,
    "failureReason": string | null
  }
}

APIエンドポイント応答構造

GET /age-verification/get-statusエンドポイントは直接応答を返します：

{
  "id": "uuid",
  "status": "PASS" | "FAIL" | "PENDING" | "IN_PROGRESS",
  "ageCategory": "adult" | "digital-youth" | "digital-minor" | null,
  "method": "id-document" | "credit-card" | "self-confirmation" | "social-security-number" | "email-confirmation" | "age-estimation-scan" | null,
  "age": {
    "low": number,
    "high": number
  } | null,
  "dob": "YYYY-MM-DD" | null,
  "failureReason": string | null
}

クエリパラメータ:

id (必須): 検証ID
includeDob (オプション、デフォルト: false): trueの場合、利用可能な場合にdobフィールドを含めます

完全なエンドポイントドキュメントについては、GET /age-verification/get-statusを参照してください。

WebhookとAPIエンドポイントの主な違い

側面	Webhookイベント	APIエンドポイント
ステータス値	`PASS`または`FAIL`のみ	`PASS`、`FAIL`、`PENDING`、`IN_PROGRESS`
構造	`{ eventType, data }`でラップ	直接応答オブジェクト
DOBフィールド	利用可能な場合は常に含まれる	`includeDob=true`クエリパラメータが設定されている場合にのみ含まれる
AgeCategory	ステータスが`PASS`の場合にのみ存在	`PASS`と`FAIL`の両方のステータスで存在
Method	ステータスが`PASS`の場合にのみ存在	`PASS`と`FAIL`の両方のステータスで存在
利用可能なタイミング	検証が完了したときのみ	検証中を含め、いつでもポーリング可能

ステータスタイプ

PASS

検証が成功し、ユーザーが年齢基準を満たしていることが確認されました。

利用可能性:

Webhook: ✅ 検証が正常に完了したときに送信されます
APIエンドポイント: ✅ 検証が完了して成功したときに返されます

FAIL

検証により、ユーザーが年齢基準を満たしていないことが確認されたか、決定的な年齢判定ができなかったため、または不正行為が検出されたため、検証プロセスが失敗しました。これらのシナリオは、適切なfailureReason値を持つFAILステータスになります。

利用可能性:

Webhook: ✅ 検証が失敗して完了したときに送信されます
APIエンドポイント: ✅ 検証が完了して失敗したときに返されます

ステータス: PENDING

検証リクエストが作成されましたが、まだ処理が開始されていません。

利用可能性:

Webhook: ❌ 送信されません（webhookは完了時のみ発火します）
APIエンドポイント: ✅ 検証が初期状態のときに返されます

PENDINGのAPIエンドポイント応答:

id (UUID) - 常に含まれます
status ("PENDING") - 常に含まれます
他のすべてのフィールドは存在しません

ステータス: IN_PROGRESS

検証は現在処理中です。

利用可能性:

Webhook: ❌ 送信されません（webhookは完了時のみ発火します）
APIエンドポイント: ✅ 検証が積極的に処理されているときに返されます

IN_PROGRESSのAPIエンドポイント応答:

id (UUID) - 常に含まれます
status ("IN_PROGRESS") - 常に含まれます
他のすべてのフィールドは存在しません

ステータス別のフィールド存在ルール

Webhookイベント

Webhookイベントは、検証が完了したとき（ステータスがPASSまたはFAIL）にのみ送信されます。PENDINGやIN_PROGRESSなどの中間ステータスは含まれません。

ステータス: `PASS`

Webhookイベント

常に含まれる:

id (UUID)
status ("PASS")
method (string) - 使用された検証方法

場合によって含まれる:

ageCategory (string) - adult、digital-youth、またはdigital-minorのいずれか（ageが存在する場合にのみ存在）
age (object) - lowとhighの両方の境界を含む（検証方法が年齢情報を提供する場合にのみ存在）
dob (string, YYYY-MM-DD形式) - 確認された生年月日、検証方法が提供する場合にのみ（特定の方法については生年月日フィールドセクションを参照）。利用可能な場合は常に含まれます。

含まれない:

failureReason

APIエンドポイント

常に含まれる:

id (UUID)
status ("PASS")
method (string) - 使用された検証方法（利用可能な場合）

場合によって含まれる:

ageCategory (string) - adult、digital-youth、またはdigital-minorのいずれか（年齢が存在する場合）
age (object) - lowとhighの両方の境界を含む（検証方法が年齢情報を提供する場合）

場合によって含まれる:

dob (string, YYYY-MM-DD形式) - includeDob=trueクエリパラメータが設定されている場合、かつ検証方法が提供する場合にのみ含まれます（特定の方法については生年月日フィールドセクションを参照）

含まれない:

failureReason

知っておくべきこと

PASSステータスを成功した検証として扱います
ageCategoryフィールドが存在する場合は、ユーザーの権限とアクセスレベルを決定するために使用します
ageCategoryが存在する場合、アクセス制御にage.lowやage.highのみに依存せず、代わりにageCategoryを使用します
dobが提供されている場合は使用できますが、常に利用可能であると想定しないでください
APIエンドポイントの場合: DOBデータが必要な場合は、クエリパラメータでincludeDob=trueを設定します（GET /age-verification/get-statusを参照）

ステータス: `FAIL`

Webhookイベント

常に含まれる:

id (UUID)
status ("FAIL")
failureReason (string) - 失敗の理由

場合によって含まれる:

method (string) - 失敗がmax-attempts-exceededまたはfraudulent-activity-detectedによるものでない場合にのみ存在
age (object) - failureReasonがage-criteria-not-metの場合にのみ存在
dob (string) - 検証方法が提供する場合にのみ存在（特定の方法については生年月日フィールドセクションを参照）。利用可能な場合は常に含まれます。

含まれない:

ageCategory - Webhookイベントは、ステータスがPASSの場合にのみageCategoryを含みます

APIエンドポイント

常に含まれる:

id (UUID)
status ("FAIL")
failureReason (string) - 失敗の理由

場合によって含まれる:

method (string) - 失敗がage-criteria-not-metによる場合にのみ存在
age (object) - failureReasonがage-criteria-not-metの場合にのみ存在
ageCategory (string) - ageが存在する場合にのみ存在
dob (string) - includeDob=trueクエリパラメータが設定されている場合、かつ検証方法が提供する場合にのみ含まれます（特定の方法については生年月日フィールドセクションを参照）

含まれない:

ageが存在しない場合のageCategory

知っておくべきこと

FAILステータスを失敗した検証として扱い、アクセスや権限を付与しないでください
検証が失敗した理由を理解するために、常にfailureReasonを確認してください
FAILステータスでageフィールドが存在するとは想定しないでください。利用できない場合があります
FAIL結果でageが存在する場合、ログ記録や分析に使用できますが、アクセス制御の決定には使用しないでください
methodとageが存在しない場合を処理してください。これはシステムレベルの失敗を示し、年齢判定の失敗ではありません
Webhookイベントの場合: FAILステータスではageCategoryは存在しないため、使用しようとしないでください
APIエンドポイントの場合: FAILステータスでageCategoryが存在する場合でも、アクセス制御の決定には使用しないでください

一般的な失敗理由:

age-criteria-not-met - ユーザーの確認された年齢が必要なしきい値を満たしていません
max-attempts-exceeded - ユーザーが利用可能なすべての検証試行を尽くしました（これは、失敗または不確定な年齢判定の後にユーザーが再試行を尽くした場合の最終的な失敗理由です）
fraudulent-activity-detected - システムが不審または不正な行動を検出しました

年齢フィールドの設定ルール

`age`オブジェクトが存在する場合

ageオブジェクトには2つのフィールドが含まれます：

low (number): 年齢推定の下限、またはハード検証方法（例：ID文書）の正確な年齢
high (number): 年齢推定の上限、またはハード検証方法の正確な年齢、または最小年齢のみがわかっている場合は150

ageが存在する条件:

検証方法が年齢情報を提供した
FAILステータスの場合: failureReasonがage-criteria-not-met

知っておくべきこと

ageオブジェクトにアクセスする前に、age.lowとage.highの両方が存在することを確認してください
age.low === age.highが正確な年齢を意味すると想定しないでください。そうなる場合もありますが、検証方法によって異なります
statusがPASSでない場合、アクセス制御にageフィールドを使用しないでください
PASSステータスの場合、アクセス決定を行う際は、生のage値よりもageCategoryを使用することを推奨します

`ageCategory`が存在する場合

ageCategoryフィールドは、年齢と管轄情報から導出されます。

値:

adult - ユーザーは成人として分類されます
digital-youth - ユーザーはデジタルユースとして分類されます（年齢制限があるが未成年ではない）
digital-minor - ユーザーはデジタル未成年として分類されます

ageCategoryが存在する条件:

ageオブジェクトが存在する
年齢と管轄から年齢カテゴリが正常に計算された
FAILステータスの場合: failureReasonがage-criteria-not-met

知っておくべきこと

ステータスがPASSでageCategoryが存在する場合、アクセス制御の決定にageCategoryを使用します
ageが存在する場合でも、ageCategoryが常に存在するとは想定しないでください
ageが存在するがageCategoryが存在しない場合を処理してください
FAILステータスの場合、存在する場合でも、アクセス制御の決定にageCategoryを使用しないでください

`age`と`ageCategory`が存在しない場合

条件:

検証がmax-attempts-exceededのfailureReasonで失敗した - 年齢判定は行われませんでした
検証がfraudulent-activity-detectedのfailureReasonで失敗した - セキュリティ上の理由で年齢データが除外されました
検証方法が年齢情報を提供しなかった

知っておくべきこと

年齢情報が常に利用可能であると想定せず、欠落している年齢フィールドを適切に処理してください
ageが存在しない場合、他のフィールドから年齢を推測しようとしないでください
年齢フィールドがないFAILステータスの場合、何が間違っていたかを理解するためにfailureReasonに依存してください

生年月日フィールド

形式: YYYY-MM-DD (ISO 8601日付形式)

存在する場合: dobフィールドは、検証方法が確認された生年月日を提供する場合にのみ含まれます。年齢推定または年齢範囲のみを提供する方法では含まれません。検証方法と管轄の様々な組み合わせを考慮すると、dobがいつ存在しなければならないかについて検証や期待を行うべきではありません。このフィールドは検証方法から利用可能な場合に提供されますが、すべてのシナリオでその存在を保証することはできません。

dobを提供できる方法:

id-document - ID文書に読み取り可能な生年月日情報が含まれている場合
credit-card - クレジットカード検証が生年月日を提供する場合（すべてのクレジットカード検証にDOBが含まれるわけではありません）
social-security-number - SSN検証が生年月日を提供する場合
privy - 常に提供されます（インドネシアの本人確認）
korean-real-name - 常に提供されます（Inicis経由の韓国の実名確認）
age-attestation - 証明に生年月日情報が含まれている場合
singpass - 常に提供されます（シンガポールの国民本人確認）

dobを提供しない方法:

age-estimation-scan - 年齢範囲のみを提供し、確認されたDOBは提供しません
email-confirmation - 年齢推定のみを提供し、確認されたDOBは提供しません
email-estimation - 年齢推定のみを提供し、確認されたDOBは提供しません
self-confirmation - 確認されたDOBは利用できません

ステータス条件:

方法が提供する場合、PASSステータスで存在
ユーザーが年齢基準を満たしていないと判定される前に方法が提供した場合、FAILステータスで存在

知っておくべきこと

PASSステータスでも、dobが常に存在するとは想定しないでください
dobが存在する場合、YYYY-MM-DD形式であることを確認してください
dobを追加の検証やログ記録に使用できますが、年齢を決定する主要な方法として依存しないでください

方法フィールド

存在する場合:

PASSステータスの場合は常に存在
FAILステータスの場合、failureReasonがage-criteria-not-metの場合に存在

可能な値:

id-document - 政府発行のID文書検証（DOBを含む場合があります）
credit-card - クレジットカード検証（DOBを含む場合があります）
self-confirmation - 自己申告の年齢確認（DOBなし）
age-estimation-scan - 文書スキャンによる年齢推定（DOBなし、年齢範囲のみ）
social-security-number - SSNベースの検証（DOBを含む場合があります）
email-confirmation - メールベースの年齢検証（DOBなし、年齢推定のみ）
email-estimation - メールベースの年齢推定（DOBなし、年齢推定のみ）
privy - インドネシアの本人確認（常にDOBを含む）
korean-real-name - Inicis経由の韓国の実名確認（常にDOBを含む）
age-attestation - k-ID経由の年齢証明（DOBを含む場合があります）
singpass - シンガポールの国民本人確認（常にDOBを含む）
connect-id - オーストラリアのConnectID検証

知っておくべきこと

分析やログ記録の目的でmethodを使用できます
アクセス制御の決定にmethodを使用しないでください

失敗理由の値

一般的なfailureReason値：

age-criteria-not-met - ユーザーの確認された年齢が必要なしきい値を満たしていません
max-attempts-exceeded - ユーザーが利用可能なすべての検証試行を尽くしました
fraudulent-activity-detected - システムが不審または不正な行動を検出しました

知っておくべきこと

未知のfailureReason値を適切に処理し、予期しない値が表示されても壊れないようにしてください
failureReasonのみに基づいてアクセス決定を行わず、常にstatusフィールドを考慮してください
デバッグや分析の目的でfailureReasonをログに記録することをお勧めします

完全なフィールドマトリックス

Webhookイベント

フィールド	PASS	FAIL
`id`	always	always
`status`	always	always
`method`	always	sometimes¹
`ageCategory`	sometimes²	never
`age`	sometimes²	sometimes³
`dob`	sometimes⁴	sometimes⁴
`failureReason`	never	always

¹ failureReasonがmax-attempts-exceededまたはfraudulent-activity-detectedでない限り存在
² age.lowとage.highの両方が利用可能な場合にのみ存在
³ age.lowとage.highの両方が利用可能で、かつfailureReasonがmax-attempts-exceededまたはfraudulent-activity-detectedでない場合にのみ存在
⁴ 検証方法から利用可能な場合は常に含まれます

APIエンドポイント

フィールド	PENDING	IN_PROGRESS	PASS	FAIL
`id`	always	always	always	always
`status`	always	always	always	always
`method`	never	never	sometimes²	sometimes¹
`ageCategory`	never	never	sometimes²	sometimes²
`age`	never	never	sometimes²	sometimes³
`dob`	never	never	sometimes⁴	sometimes⁴
`failureReason`	never	never	never	always

¹ failureReasonがmax-attempts-exceededまたはfraudulent-activity-detectedでない限り存在
² age.lowとage.highの両方が利用可能な場合にのみ存在
³ age.lowとage.highの両方が利用可能で、かつfailureReasonがmax-attempts-exceededまたはfraudulent-activity-detectedでない場合にのみ存在
⁴ includeDob=trueクエリパラメータが設定され、かつ検証方法から利用可能な場合にのみ含まれます

ペイロードの例

Webhookイベントの例

年齢情報を含むPASSステータス

{
  "eventType": "Verification.Result",
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "status": "PASS",
    "method": "id-document",
    "ageCategory": "adult",
    "age": {
      "low": 25,
      "high": 25
    },
    "dob": "1998-05-15"
  }
}

年齢情報を含むFAILステータス

{
  "eventType": "Verification.Result",
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174001",
    "status": "FAIL",
    "method": "age-estimation-scan",
    "failureReason": "age-criteria-not-met",
    "age": {
      "low": 16,
      "high": 17
    }
  }
}

年齢情報を含まないFAILステータス

{
  "eventType": "Verification.Result",
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174002",
    "status": "FAIL",
    "failureReason": "max-attempts-exceeded"
  }
}

APIエンドポイント応答の例

PENDINGステータス

{
  "id": "123e4567-e89b-12d3-a456-426614174003",
  "status": "PENDING"
}

IN_PROGRESSステータス

{
  "id": "123e4567-e89b-12d3-a456-426614174004",
  "status": "IN_PROGRESS"
}

年齢情報を含むPASSステータス（DOBなし）

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "PASS",
  "method": "id-document",
  "ageCategory": "adult",
  "age": {
    "low": 25,
    "high": 25
  }
}

DOBを含むPASSステータス（includeDob = true）

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "PASS",
  "method": "id-document",
  "ageCategory": "adult",
  "age": {
    "low": 25,
    "high": 25
  },
  "dob": "1998-05-15"
}

年齢情報を含むFAILステータス

{
  "id": "123e4567-e89b-12d3-a456-426614174001",
  "status": "FAIL",
  "method": "age-estimation-scan",
  "failureReason": "age-criteria-not-met",
  "age": {
    "low": 16,
    "high": 17
  },
  "ageCategory": "digital-minor"
}

年齢情報を含まないFAILステータス

{
  "id": "123e4567-e89b-12d3-a456-426614174002",
  "status": "FAIL",
  "failureReason": "max-attempts-exceeded"
}

実装チェックリスト

Webhookイベント

APIエンドポイント

実装ノート

AgeCategoryの動作

ageCategoryフィールドは、WebhookイベントではステータスがPASSの場合にのみ含まれます。これにより、年齢カテゴリ情報は検証が成功した場合にのみ提供されます。APIエンドポイントは、一部の場合にFAILステータスでageCategoryを含むことができますが、アクセス制御の決定に使用すべきではないことに注意してください。

バージョン履歴

2024-12-05: 初期APIコントラクトドキュメント

フィールド​

例​

検証イベントコントラクト​

概要​

データ構造​

Webhookイベント構造​

APIエンドポイント応答構造​

WebhookとAPIエンドポイントの主な違い​

ステータスタイプ​

PASS​

FAIL​

ステータス: PENDING​

ステータス: IN_PROGRESS​

ステータス別のフィールド存在ルール​

Webhookイベント​

ステータス: PASS​

ステータス: FAIL​

年齢フィールドの設定ルール​

ageオブジェクトが存在する場合​

ageCategoryが存在する場合​

ageとageCategoryが存在しない場合​

生年月日フィールド​

方法フィールド​

失敗理由の値​

完全なフィールドマトリックス​

Webhookイベント​

APIエンドポイント​

ペイロードの例​

Webhookイベントの例​

APIエンドポイント応答の例​

実装チェックリスト​

Webhookイベント​

APIエンドポイント​

実装ノート​

バージョン履歴​

フィールド

例

検証イベントコントラクト

概要

データ構造

Webhookイベント構造

APIエンドポイント応答構造

WebhookとAPIエンドポイントの主な違い

ステータスタイプ

PASS

FAIL

ステータス: PENDING

ステータス: IN_PROGRESS

ステータス別のフィールド存在ルール

Webhookイベント

ステータス: `PASS`

ステータス: `FAIL`

年齢フィールドの設定ルール

`age`オブジェクトが存在する場合

`ageCategory`が存在する場合

`age`と`ageCategory`が存在しない場合

生年月日フィールド

方法フィールド

失敗理由の値

完全なフィールドマトリックス

Webhookイベント

APIエンドポイント

ペイロードの例

Webhookイベントの例

APIエンドポイント応答の例

実装チェックリスト

Webhookイベント

APIエンドポイント

実装ノート

バージョン履歴