Verification.Result
確認試行の結果とともに発行されます。
配信とリカバリー
webhookイベントは失敗時に最大2回リトライされます。サーバーがイベントを受信できなかった場合、保存した確認IDを使用してGET /age-verification/get-statusをポーリングしてください。詳細は配信、リトライ、リカバリーを参照してください。
フィールド
| フィールド | タイプ | 必須 | 説明 |
|---|---|---|---|
eventType | string | はい | 常に"Verification.Result" |
data | object | はい | 確認結果データ |
data.id | string (UUID) | はい | 一意の確認ID |
data.status | string | はい | PASSまたはFAILのいずれか |
data.ageCategory | string | いいえ | 推定年齢カテゴリ。adult、digital-youth、またはdigital-minorのいずれか。PASSステータスの場合、プロダクトの設定で選択されていれば存在します。FAILステータスの場合、failureReasonがage-criteria-not-metでageが存在する場合にのみ存在します。受け取る年齢フィールドを選ぶを参照してください |
data.ageBand | object | いいえ | 年齢が当てはまる年齢区分。ageCategoryが存在し、確認の管轄に対する区分に年齢が収まる場合にのみ存在します。年齢区分を参照してください |
data.ageBand.key | string | はい | 区分の安定した識別子。nameではなくこの値で照合してください |
data.ageBand.name | string | はい | 区分名。例: 11-13、18+ |
data.ageBand.lowerAge | number | はい | 区分に含まれる最小の年齢 |
data.ageBand.upperAge | number | いいえ | 区分に含まれる最大の年齢。18+のような上限のない区分では存在しません |
data.method | string | いいえ | 使用された確認方法。PASSステータスの場合は常に存在します。FAILステータスの場合、failureReasonがage-criteria-not-metの場合にのみ存在します |
data.provider | string | いいえ | メソッドを実行したベンダー。methodが存在する場合は常に存在します |
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) | いいえ | 確認された生年月日。確認方法が提供し、プロダクトのWebhook設定が含める場合にのみ含まれます |
例
{
"eventType": "Verification.Result",
"data": {
"id": "4e57301e-a4d1-498f-ac3f-f3d4de19abf6",
"status": "PASS",
"method": "id-document",
"provider": "veratad",
"age": {
"low": 43,
"high": 43
},
"dob": "1981-06-20"
}
}受け取る年齢フィールドを選ぶ
確認結果を受け取る方法ごとに、k-IDが返す年齢フィールドを選べます。Compliance Studioでプロダクトを開き、Product accessに進んで、Age resultカードを見つけてください。
カードには3つのチャネルがあります。
| チャネル | 対象 |
|---|---|
| Get status | GET /age-verification/get-statusのレスポンス |
| Webhooks | Verification.Resultなど、確認結果を運ぶWebhookイベント |
| JavaScript result | 確認画面があなたのページに送信する結果メッセージ |
各チャネルには3つのトグルがあります。
- Date of birthは
dobを制御します。 - Ageは
ageを制御します。 - Age categoryは
ageCategoryとageBandを制御します。
k-IDは、チャネルの設定で選択されているフィールドだけをそのチャネルで返します。各チャネルの設定は互いに独立しています。
トグルを変更して保存するまで、プロダクト独自の設定はありません。その間、k-IDは組織の設定に従います。カードには現在のデフォルトが表示されます。
設定の変更は、プロダクトを公開した後に反映されます。
includeDobクエリパラメータ
GET /age-verification/get-statusのincludeDobクエリパラメータは、レスポンスにdobを含めるかどうかを決めます。優先順位は、プロダクトに保存済みのAge result設定があるかどうかで変わります。
| プロダクト | includeDobの値 | 結果 |
|---|---|---|
| 保存済みの設定あり | trueまたはfalse | パラメータがGet statusのDate of birthトグルより優先されます |
| 保存済みの設定あり | 送信しない | Get statusのDate of birthトグルが決めます |
| 保存済みの設定なし | true | dobが含まれます。ただし、組織が合否のみを返す設定の場合は含まれません |
| 保存済みの設定なし | falseまたは送信しない | dobは含まれません |
includeDobパラメータはget-statusにのみ適用されます。WebhookイベントとJavaScript結果は、それぞれのトグルに従います。
検証イベントコントラクト
概要
このセクションは、2つのメカニズムを通じて提供される検証ステータスのAPIコントラクトを定義します:
- Webhookイベント: 検証が完了したときに送信される
Verification.ResultWebhookイベント - 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",
"method": "id-document" | "credit-card" | "self-confirmation" | "social-security-number" | "email-confirmation" | "age-estimation-scan",
"provider": string,
"age": {
"low": number,
"high": number
},
"dob": "YYYY-MM-DD",
"failureReason": string
}
}APIエンドポイント応答構造
GET /age-verification/get-statusエンドポイントは直接応答を返します:
{
"id": "uuid",
"status": "PASS" | "FAIL" | "PENDING" | "IN_PROGRESS",
"ageCategory": "adult" | "digital-youth" | "digital-minor",
"method": "id-document" | "credit-card" | "self-confirmation" | "social-security-number" | "email-confirmation" | "age-estimation-scan",
"provider": string,
"age": {
"low": number,
"high": number
},
"dob": "YYYY-MM-DD",
"failureReason": string
}クエリパラメータ:
id(必須): 検証IDincludeDob(オプション):trueまたはfalseの場合、プロダクトに保存済みのAge result設定があるとき、Get statusのDate of birthトグルを上書きします。保存済みの設定がない場合、trueは利用可能なときにdobフィールドを含め、それ以外の値では含めません。includeDobクエリパラメータを参照してください
完全なエンドポイントドキュメントについては、GET /age-verification/get-statusを参照してください。
WebhookとAPIエンドポイントの主な違い
| 側面 | Webhookイベント | APIエンドポイント |
|---|---|---|
| ステータス値 | PASSまたはFAILのみ | PASS、FAIL、PENDING、IN_PROGRESS |
| 構造 | { eventType, data }でラップ | 直接応答オブジェクト |
| DOBフィールド | 利用可能で、WebhookのDate of birthトグルが許可する場合に含まれる | includeDobクエリパラメータとGet statusのDate of birthトグルに従う(優先順位を参照) |
| AgeCategory | PASSステータスの場合(プロダクトの設定で選択されている場合)、およびFAILステータスでfailureReasonがage-criteria-not-metの場合に存在 | 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) - 使用された検証方法provider(string) - メソッドを実行したベンダー
プロダクトの設定で選択されている場合に含まれる:
age(object) -lowとhighの両方の境界を含むageCategory(string) -adult、digital-youth、またはdigital-minorのいずれか
場合によって含まれる:
ageBand(object) - 年齢が当てはまる年齢区分。ageCategoryが存在する場合にのみ存在します(年齢区分を参照)dob(string, YYYY-MM-DD形式) - 確認された生年月日。検証方法が提供し、プロダクトのWebhook設定が含める場合にのみ含まれます(特定の方法については生年月日フィールドセクションを参照)
含まれない:
failureReason
APIエンドポイント
常に含まれる:
id(UUID)status("PASS")method(string) - 使用された検証方法(利用可能な場合)provider(string) - メソッドを実行したベンダー(利用可能な場合)
プロダクトの設定で選択されている場合に含まれる:
age(object) -lowとhighの両方の境界を含むageCategory(string) -adult、digital-youth、またはdigital-minorのいずれか
場合によって含まれる:
ageBand(object) - 年齢が当てはまる年齢区分。ageCategoryが存在する場合にのみ存在します(年齢区分を参照)dob(string, YYYY-MM-DD形式) -includeDobクエリパラメータまたはGet statusのDate of birthトグルが許可し、かつ検証方法が提供する場合にのみ含まれます(includeDobクエリパラメータと、特定の方法については生年月日フィールドセクションを参照)
含まれない:
failureReason
知っておくべきこと
- PASSステータスを成功した検証として扱います
- PASSとなるすべての検証方法が年齢情報を提供しますが、各チャネルに
age、ageCategory、dobを含めるかどうかはプロダクトの設定で決まります。ageやageCategoryが存在すると想定しないでください - ユーザーの権限とアクセスレベルを決定するために
ageCategoryフィールドを使用します - アクセス制御に
age.lowやage.highのみに依存せず、代わりにageCategoryを使用します dobが提供されている場合は使用できますが、常に利用可能であると想定しないでください- APIエンドポイントの場合: DOBデータが必要な場合は、クエリパラメータで
includeDob=trueを設定します。プロダクトに保存済みのAge result設定がある場合、パラメータがトグルより優先されます(GET /age-verification/get-statusと優先順位を参照)
ステータス: FAIL
Webhookイベント
常に含まれる:
id(UUID)status("FAIL")failureReason(string) - 失敗の理由
場合によって含まれる:
method(string) - 失敗がmax-attempts-exceededまたはfraudulent-activity-detectedによるものでない場合にのみ存在provider(string) -methodが存在する場合にのみ存在age(object) -failureReasonがage-criteria-not-metの場合にのみ存在ageCategory(string) -failureReasonがage-criteria-not-metでageが存在する場合にのみ存在ageBand(object) -ageCategoryが存在する場合にのみ存在します(年齢区分を参照)dob(string) - 検証方法が提供し、プロダクトのWebhook設定が含める場合にのみ存在します(特定の方法については生年月日フィールドセクションを参照)。
APIエンドポイント
常に含まれる:
id(UUID)status("FAIL")failureReason(string) - 失敗の理由
場合によって含まれる:
method(string) - 失敗がage-criteria-not-metによる場合にのみ存在provider(string) -methodが存在する場合にのみ存在age(object) -failureReasonがage-criteria-not-metの場合にのみ存在ageCategory(string) -ageが存在する場合にのみ存在ageBand(object) -ageCategoryが存在する場合にのみ存在します(年齢区分を参照)dob(string) -includeDobクエリパラメータまたはGet statusのDate of birthトグルが許可し、かつ検証方法が提供する場合にのみ含まれます(特定の方法については生年月日フィールドセクションを参照)
含まれない:
ageが存在しない場合のageCategory
知っておくべきこと
FAILステータスを失敗した検証として扱い、アクセスや権限を付与しないでください- 検証が失敗した理由を理解するために、常に
failureReasonを確認してください - FAILステータスで
ageフィールドが存在するとは想定しないでください。利用できない場合があります FAIL結果でageが存在する場合、ログ記録や分析に使用できますが、アクセス制御の決定には使用しないでくださいmethodとageが存在しない場合を処理してください。これはシステムレベルの失敗を示し、年齢判定の失敗ではありません- Webhookイベントの場合:
FAILステータスでfailureReasonがage-criteria-not-metの場合、ageCategoryが存在する可能性がありますが、アクセス制御の決定には使用しないでください - APIエンドポイントの場合:
FAILステータスでageCategoryが存在する場合でも、アクセス制御の決定には使用しないでください
一般的な失敗理由:
age-criteria-not-met- ユーザーの確認された年齢が必要なしきい値を満たしていませんmax-attempts-exceeded- ユーザーが利用可能なすべての検証試行を尽くしました(これは、失敗または不確定な年齢判定の後にユーザーが再試行を尽くした場合の最終的な失敗理由です)fraudulent-activity-detected- システムが不審または不正な行動を検出しました
年齢フィールドの設定ルール
ageオブジェクトが存在する場合
ageオブジェクトには2つのフィールドが含まれます:
low(number): 年齢推定の下限、またはハード検証方法(例:ID文書)の正確な年齢。検証方法が正確な年齢を提供しない場合、これは検証に必要な最小年齢のしきい値です。high(number): 年齢推定の上限、またはハード検証方法の正確な年齢。検証方法が正確な年齢を提供しない場合、これは100です。
ageが存在する条件:
- PASSステータスの場合: プロダクトの設定でチャネルの
ageが選択されている場合に存在します。PASSとなるすべての検証方法が年齢情報を提供します - FAILステータスの場合:
failureReasonがage-criteria-not-met
知っておくべきこと
- PASSステータスでは、プロダクトの設定でチャネルの
ageが選択されていない場合、ageは存在しません。アクセスの判断にはageCategoryを使用してください ageオブジェクトが存在すること、およびage.lowとage.highの両方が存在することを確認してから読み取ってくださいage.low === age.highが正確な年齢を意味すると想定しないでください。そうなる場合もありますが、検証方法によって異なりますstatusがPASSでない場合、アクセス制御にageフィールドを使用しないでください- PASSステータスの場合、アクセス決定を行う際は、生の
age値よりもageCategoryを使用することを推奨します
ageCategoryが存在する場合
ageCategoryフィールドは、年齢と管轄情報から導出されます。
値:
adult- ユーザーは成人として分類されますdigital-youth- ユーザーはデジタルユースとして分類されます(年齢制限があるが未成年ではない)digital-minor- ユーザーはデジタル未成年として分類されます
ageCategoryが存在する条件:
- PASSステータスの場合: プロダクトの設定でチャネルの
ageCategoryが選択されている場合に存在します。k-IDは検証が成功したときに常に年齢カテゴリを計算します - FAILステータスの場合:
failureReasonがage-criteria-not-metで年齢データが利用可能な場合(age.lowとage.highの両方が存在する場合)に存在します
知っておくべきこと
- PASSステータスの場合、プロダクトの設定でチャネルの
ageCategoryが選択されていればageCategoryは存在します。存在する場合は、アクセス制御の決定に使用できます - 生の
age値ではなく、アクセス制御の決定にageCategoryを使用してください - FAILステータスの場合、存在する場合でも、アクセス制御の決定に
ageCategoryを使用しないでください
ageとageCategoryが存在しない場合
条件:
- 検証はPASSで、プロダクトの設定でそのチャネルのフィールドが選択されていなかった。その場合、
PASS結果がage、ageCategory、またはその両方なしで届くことがあります - 検証が
max-attempts-exceededのfailureReasonで失敗した - 年齢判定は行われませんでした - 検証が
fraudulent-activity-detectedのfailureReasonで失敗した - セキュリティ上の理由で年齢データが除外されました - 検証方法が年齢情報を提供しなかった
知っておくべきこと
- 年齢情報が常に利用可能であると想定せず、欠落している年齢フィールドを適切に処理してください
ageが存在しない場合、他のフィールドから年齢を推測しようとしないでください- 年齢フィールドがないFAILステータスの場合、何が間違っていたかを理解するために
failureReasonに依存してください
年齢区分
ageBandフィールドは、確認された年齢が当てはまる年齢区分を示します。区分は、確認の管轄に対するプロダクトの年齢区分から取得されます。区分はCompliance StudioのProduct accessタブにあるAge bandsカードで設定します。
ageBandオブジェクトには次のフィールドがあります。
key(string): 安定した識別子。nameは変更される可能性があるため、この値で照合してください。name(string): 区分名。例:11-13。lowerAge(number): 区分に含まれる最小の年齢。upperAge(number): 区分に含まれる最大の年齢(この値を含む)。18+のような上限のない区分では存在しません。
ageBandが存在する条件:
- チャネルで
ageCategoryが含まれている。ageCategoryが含まれない場合、ageBandも含まれません。 - 年齢が、確認の管轄に対する区分に収まる。k-IDは
age.lowで年齢を区分に当てはめます。 - その管轄に区分が存在する。完全一致する管轄のプロダクト独自の区分が最初に適用され、次にその国のプロダクト独自の区分、最後にその国に対するk-IDのデフォルト区分が適用されます。k-IDのデフォルト区分があるのはインドネシア(
ID)のみです。他の市場では、区分を自分で設定する必要があります。
ageBandが存在しない場合:
- 年齢が最初の区分より下である。
- その管轄に適用される区分がない。
- チャネルで
ageCategoryが含まれていない。
k-IDが区分を決定するタイミング:
- Webhookは、確認が完了した時点の区分を含みます。
- get-statusは、呼び出すたびに現在の区分から区分を決定します。
- 確認の完了後に区分を変更した場合、get-statusは、その確認についてWebhookが送信した区分とは異なる区分を返すことがあります。
区分は市場ごとに異なります。 各市場はそれぞれ独自の区分を使用するため、同じ年齢でも市場によって異なる区分に入ることがあります。どこでも同じグループ分けにしたい場合は、すべての市場に同じ区分を設定してください。
ManualAgeAppeal.PendingReviewイベントはWebhooksチャネルのAgeとAge categoryのトグルに従いますが、ageBandは含まれません。
例: upperAgeのない18+区分
{
"eventType": "Verification.Result",
"data": {
"id": "0b83055f-642a-44f5-8abb-e37cb907dfcd",
"status": "PASS",
"ageCategory": "adult",
"ageBand": {
"key": "18-plus",
"name": "18+",
"lowerAge": 18
},
"method": "id-document",
"provider": "veratad",
"age": {
"low": 30,
"high": 30
}
}
}知っておくべきこと
ageBandは省略可能なものとして扱い、アクセス制御には使用しないでください。ageCategoryを使用してください。ageBand.nameではなくageBand.keyで照合してください。ageBandがなくても、確認が失敗したことを意味しません。ageBandは、社内向けに使う独自のグループ分けです。ageCategoryは、k-IDのコンプライアンスエンジンが管轄のルールから決定する法的なカテゴリーです。- この2つは一致しないことがあります。たとえばインドネシアでは、19歳はデフォルトの
18+区分に入りますが、インドネシアの成年年齢は21歳であるためdigital-youthになります。
生年月日フィールド
形式: YYYY-MM-DD (ISO 8601日付形式)
存在する場合:
dobフィールドは、検証方法が確認された生年月日を提供する場合にのみ含まれます。年齢推定または年齢範囲のみを提供する方法では含まれません。検証方法と管轄の様々な組み合わせを考慮すると、dobがいつ存在しなければならないかについて検証や期待を行うべきではありません。このフィールドは検証方法から利用可能な場合に提供されますが、すべてのシナリオでその存在を保証することはできません。
dobを提供できる方法:
id-document- ID文書に読み取り可能な生年月日情報が含まれている場合privy- 常に提供されます(インドネシアの本人確認)korean-real-name- 常に提供されます(Inicis経由の韓国の実名確認)age-attestation- 証明に生年月日情報が含まれている場合singpass- 常に提供されます(シンガポールの国民本人確認)
dobを提供しない方法:
age-estimation-scan- 年齢範囲のみを提供し、確認されたDOBは提供しませんconnect-id- 年齢しきい値を満たしているかのみを確認し、生年月日は提供しませんcredit-card- 成人のカード保有者であることを確認するもので、生年月日は提供しませんemail-estimation- 年齢推定のみを提供し、確認されたDOBは提供しませんsocial-security-number- 成人の本人情報を確認するもので、生年月日は提供しません
ステータス条件:
- 方法が提供する場合、PASSステータスで存在
- ユーザーが年齢基準を満たしていないと判定される前に方法が提供した場合、FAILステータスで存在
知っておくべきこと
- PASSステータスでも、
dobが常に存在するとは想定しないでください dobが存在する場合、YYYY-MM-DD形式であることを確認してくださいdobを追加の検証やログ記録に使用できますが、年齢を決定する主要な方法として依存しないでください
方法フィールド
存在する場合:
- PASSステータスの場合は常に存在
- FAILステータスの場合、
failureReasonがage-criteria-not-metの場合に存在
可能な値:
id-document- 政府発行のID文書検証(DOBを含む場合があります)credit-card- クレジットカード検証age-estimation-scan- 顔年齢推定スキャン(DOBなし、年齢範囲を返す)social-security-number- SSNベースの検証email-estimation- メールベースの年齢推定(DOBなし、年齢推定のみ)privy- インドネシアの本人確認(常にDOBを含む)korean-real-name- Inicis経由の韓国の実名確認(常にDOBを含む)age-attestation- k-ID経由の年齢証明(DOBを含む場合があります)singpass- シンガポールの国民本人確認(常にDOBを含む)age-key- 発行済みのAgeKeybrazil-cpf- ブラジルのCPF検証email-confirmation- 確認済みの保護者のメールアドレスpre-verified- 事前に確認済みとして申告された保護者self-confirmation- 保護者による自己申告connect-id- オーストラリアのConnectID検証
知っておくべきこと
- 分析やログ記録の目的で
methodを使用できます - アクセス制御の決定に
methodを使用しないでください
プロバイダーフィールド
存在する場合:
methodが存在する場合は常に存在
取り得る値:
connect-id, inicis, k-id, kws, openage, persona, pre-verified, privateid, privately, privy, serpro, singpass, spruce-id, stripe, veratad, verify-my, xsolla
メソッドからプロバイダーは一意に決まりません。age-estimation-scanは複数のベンダーが提供しており、credit-cardは決済が確認の代わりになった場合にレコードマーチャントを示します。
知っておくべきこと
- 分析やログ記録の目的で
providerを使用できます - アクセス制御の決定に
providerを使用しないでください - 未知の
provider値も適切に処理してください。k-IDは順次ベンダーを追加します
失敗理由の値
一般的な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¹ |
provider | always | sometimes¹ |
age | sometimes⁴ | sometimes² |
ageCategory | sometimes⁴ | sometimes² |
ageBand | sometimes⁵ | sometimes⁵ |
dob | sometimes³ | sometimes³ |
failureReason | never | always |
¹ failureReasonがmax-attempts-exceededまたはfraudulent-activity-detectedでない限り存在
² age.lowとage.highの両方が利用可能で、かつfailureReasonがage-criteria-not-metの場合にのみ存在
³ 検証方法が提供し、WebhookのDate of birthトグルが許可する場合に含まれます
⁴ プロダクトの設定でチャネルのフィールドが選択されている場合に存在します
⁵ ageCategoryが存在し、年齢が管轄の区分に収まる場合にのみ存在します
APIエンドポイント
| フィールド | PENDING | IN_PROGRESS | PASS | FAIL |
|---|---|---|---|---|
id | always | always | always | always |
status | always | always | always | always |
method | never | never | sometimes² | sometimes¹ |
provider | never | never | sometimes² | sometimes¹ |
age | never | never | sometimes⁶ | sometimes³ |
ageCategory | never | never | sometimes⁶ | sometimes⁴ |
ageBand | 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の両方が利用可能で、かつfailureReasonがage-criteria-not-metの場合にのみ存在
⁴ 年齢と管轄から年齢カテゴリが正常に計算された場合にのみ存在(FAILステータス)
⁵ includeDobクエリパラメータまたはGet statusのDate of birthトグルが許可し、かつ検証方法が提供する場合に含まれます(優先順位を参照)
⁶ プロダクトの設定でチャネルのフィールドが選択されている場合に存在します
⁷ ageCategoryが存在し、年齢が管轄の区分に収まる場合にのみ存在します
ペイロードの例
Webhookイベントの例
年齢情報を含むPASSステータス
{
"eventType": "Verification.Result",
"data": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"status": "PASS",
"method": "id-document",
"provider": "veratad",
"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",
"provider": "privately",
"failureReason": "age-criteria-not-met",
"age": {
"low": 16,
"high": 17
},
"ageCategory": "digital-minor"
}
}年齢情報を含まない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",
"provider": "veratad",
"ageCategory": "adult",
"age": {
"low": 25,
"high": 25
}
}DOBを含むPASSステータス(includeDob = true)
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"status": "PASS",
"method": "id-document",
"provider": "veratad",
"ageCategory": "adult",
"age": {
"low": 25,
"high": 25
},
"dob": "1998-05-15"
}年齢情報を含むFAILステータス
{
"id": "123e4567-e89b-12d3-a456-426614174001",
"status": "FAIL",
"method": "age-estimation-scan",
"provider": "privately",
"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イベント
- 両方のステータスタイプを処理: PASSとFAIL(webhookはPENDINGやIN_PROGRESSを送信しません)
-
age.lowやage.highにアクセスする前にageオブジェクトの存在を確認 - ステータスがPASSで
ageCategoryが存在する場合、アクセス制御にageCategoryを使用 - ステータスがFAILの場合、存在する場合でも、アクセス制御に
ageCategoryを使用しない -
methodが存在しない場合を処理(システムレベルの失敗) -
ageとageCategoryが存在しない場合を処理(特定の失敗シナリオ、またはプロダクトの設定で選択されていないフィールド) -
ageBandは省略可能なものとして扱う -
dob形式(YYYY-MM-DD)を検証(存在する場合) - デバッグのために
failureReasonをログに記録 - FAILステータスでアクセスを付与しない
- 未知の
failureReason値を適切に処理
APIエンドポイント
- すべてのステータスタイプを処理: PENDING、IN_PROGRESS、PASS、FAIL
- PENDINGとIN_PROGRESSステータスの場合、
idとstatusフィールドのみを期待 - DOBデータが必要な場合は、
includeDobクエリパラメータを設定します。プロダクトに保存済みの設定がある場合、トグルより優先されます(GET /age-verification/get-statusを参照) -
age.lowやage.highにアクセスする前にageオブジェクトの存在を確認 - ステータスがPASSで
ageCategoryが存在する場合、アクセス制御にageCategoryを使用 - ステータスがFAILの場合、存在する場合でも、アクセス制御に
ageCategoryを使用しない -
methodが存在しない場合を処理(システムレベルの失敗) -
ageとageCategoryが存在しない場合を処理(特定の失敗シナリオ、またはプロダクトの設定で選択されていないフィールド) -
ageBandは省略可能なものとして扱う -
dob形式(YYYY-MM-DD)を検証(存在する場合) - デバッグのために
failureReasonをログに記録 - FAILステータスでアクセスを付与しない
- 未知の
failureReason値を適切に処理 - PENDINGとIN_PROGRESSステータスに適切なポーリング戦略を実装
実装ノート
AgeCategoryの動作
ageCategoryフィールドは、WebhookイベントではPASSステータスの場合、プロダクトの設定で選択されていれば含まれます。FAILステータスの場合、failureReasonがage-criteria-not-metで年齢データが利用可能な場合、ageCategoryが含まれる場合があります。ただし、ステータスがFAILの場合、存在する場合でも、アクセス制御の決定にageCategoryを使用すべきではありません。APIエンドポイントも同じパターンに従います - ageCategoryは年齢データが利用可能な場合にFAILステータスで存在する可能性がありますが、アクセス制御の決定に使用すべきではありません。
バージョン履歴
- 2026-11-12: 各チャネル(get-status、Webhook、JavaScript result)は、
age、ageCategory、dobについてプロダクトのAge result設定に従うようになりました。そのため、PASS結果がageやageCategoryなしで届く場合があります。任意のageBandフィールドを追加し、includeDobの優先順位を記載しました。 - 2026-09-01: メソッドを実行したベンダーを示す
providerフィールドをWebhookイベントとAPIエンドポイントに追加しました。 - 2026-01-07:
failureReasonがage-criteria-not-metで年齢データが利用可能な場合、FAILステータスのWebhookイベントにageCategoryフィールドが含まれるようになりました。 - 2025-12-04: 初期APIコントラクトドキュメント