メインコンテンツへスキップ
POST
cURL

KYCとKYBへの対応

1つのエンドポイントで、ユーザー認証と法人確認 (KYB)の両方のセッションを作成できます。どちらが作成されるかはワークフローのタイプで決まります。
  • KYCワークフローのworkflow_idを渡す → ユーザー認証 (KYC)のセッションが作成されます。レスポンスはsession_kind: "user"です。
  • KYBワークフローのworkflow_idを渡す → 法人確認 (KYB)のセッションが作成されます。レスポンスはsession_kind: "business"です。
ワークフローはコンソールのWorkflows → Create workflowで設定します。ワークフローは作成時にKYCかKYBのどちらかに決まり、後からタイプを切り替えることはできません。

例

レスポンス (201 Created):

電子署名の書類

セッションから書類を受け取る電子署名ステップ(signature_documents_sourceがsessionまたはboth)がワークフローにある場合は、sign.documentsで書類を送信します。各書類はファイルをbase64で表したものなので、DiditがURLから書類を取得する必要はありません。
fieldsがない場合、署名者は書類を読んで同意します。

アンカーテキストでフィールドを配置する

フィールドには位置の代わりにanchorを指定できます。これは書類内のテキストで、フィールドを配置する場所の目印になります。アンカーは、Wordテンプレートなどからセッションごとに生成する書類に適しています。ワークフローの書類では、コンソールでフィールドを配置してください。 テキストが書類内にない場合、呼び出しは400とfield_anchor_not_found、およびそのフィールドのキーを返します。DiditはPDFからアンカーテキストを削除しないため、アンカーテキストはページの背景と同じ色で記述してください。

フィールドの値

sign.field_valuesは、prefillがapi.<key>であるすべてのフィールドの値を、ワークフローの書類とセッションの書類のどちらでも設定します。これらの<key>名をキーとするオブジェクトです。値は、textとdataのフィールドでは1〜500文字の文字列、checkboxではブール値です。

エラーと繰り返しの呼び出し

1つのセッションで受け付けられる書類は最大20件、合計50MBまでです。次の場合、呼び出しはsignエラーとともに400を返します。
  • ワークフローに電子署名ステップがない。
  • sign.documentsを送信したが、ステップがワークフローの書類のみを受け付ける。
  • ステップがセッションの書類のみを受け付けるのに書類を送信していない、またはステップにワークフローの書類がないのに書類を送信していない。
  • 書類が大きすぎる、有効なbase64ではない、またはサポートされていないファイルである。
  • Wordファイルがsignature_document_not_supportedで拒否された、または変換できずsignature_document_conversion_failedが返された。いずれもサポートされているファイルに記載のreasonが付きます。
  • フィールドが無効である、アンカーが見つからない(field_anchor_not_found)、またはフィールドの値が拒否された。
同じworkflow_idとvendor_dataで再度createを呼び出すと、保留中のセッションが返されます。その呼び出しでsignを送信する場合、書類、フィールド、フィールドの値は最初の呼び出しと同一(順序、タイトル、ファイル名、内容、フィールド、値がすべて同じ)でなければなりません。異なる場合は{"sign": "signature_document_changed"}とともに400が返されます。別のvendor_dataを使用するか、保留中のセッションが完了するまでお待ちください。

サンドボックスシナリオでのテスト

サンドボックスモードのアプリケーションでは、sandbox_scenarioを渡すことで、実際のプロバイダーや残高に影響を与えずに、あらかじめ決まった結果(承認、特定の却下、またはレビュー中のシナリオ)を事前に設定できます。
本番環境のアプリケーションでは、sandbox_scenarioは400で拒否されます。作成時点で結果が決まっていない場合は、セッションがまだNot Startedである限り、後からPOST /v3/session/{session_id}/sandbox/arm/で有効化(または再有効化)できます。ホスト型フローの開始前に表示されるシナリオ選択画面も、このエンドポイントを使用しています。シナリオの全一覧、マジック値の一覧、armエンドポイントのリクエストとレスポンスの形式については、サンドボックスとテストデータを参照してください。

vendor_dataでセッションをエンティティに紐付ける

  • KYCワークフローの場合: ユーザーエンティティに紐付けられます。ユーザーが存在しない場合は自動的に作成されます。
  • KYBワークフローの場合: 企業エンティティに紐付けられます。新規の場合は自動的に作成されます。
詳しくはvendor dataの紐付けをご覧ください。

イリノイ州、テキサス州、コロラド州における生体認証の同意

ホスト型フローとネイティブSDK 4.10.0以降では、アプリケーションの同意モードと本人の所在地に応じて、最初の顔撮影の前に生体認証に関する明示的な同意ステップを表示できます。この判定には、次の2つの任意フィールドが使われます。
  • user_state: 本人の居住地がわかっている場合に指定します(US-IL、IL、Illinois)。Autoモードでは、対象州の場合にフローが同意を求めます。
  • biometric_consent: すでに取得済みの同意を表す、given_atとtext_versionを含むオブジェクトです。この場合、フローは再度同意を求めません。
4.10.0未満のネイティブSDKでは、このステップを表示できません。それらのセッションは従来どおり実行され、判定では同意が未取得として報告されます。詳しくは生体認証の同意を参照してください。

重要: 開示と同意は引き続き自社プロダクト内で行う

Create Sessionは、検証URLとセッショントークンを生成します。ただし、それだけで、お客様固有のユースケースに必要な開示をユーザーに示したことや、必要な同意を取得したことを証明するものではありません。 自社のアプリケーション、Webサイト、SDKラッパー、またはホワイトラベルのフローからDiditのセッションを開始する場合は、ユーザーが撮影を始める前に、自社のUX内で法的な対応を行ってください。

推奨される検証前チェックリスト

  1. 自社が検証を依頼していること、そしてDiditがそのフローを提供する検証プロバイダー/処理者であることをユーザーに伝えます。
  2. 自社のプライバシー通知と、そのジャーニーに適用されるデータ管理者側の法的条件へのリンクを掲載します。
  3. Diditの検証に関するプライバシー通知と本人確認に関するエンドユーザー利用規約へのリンクを掲載します。
  4. ワークフローに書類の撮影、セルフィーの撮影、ライブネス、または生体認証が含まれる場合は、適用される法律または自社の法的見解で必要とされるときに、明示的な意思表示による同意を取得します。
  5. カスタムUI、カスタムドメイン、またはAPIのみのジャーニーを使用する場合は、ユーザーをDiditのフローに送る前に、これらの開示を自社のプロダクト内で表示します。
  6. 法務チームが監査証跡を求める場合は、通知/同意の文言、タイムスタンプ、関連するメタデータの記録を自社で保管します。
法的要件は法域によって異なります。ホワイトラベルのブランディングを使用しても、検証フローにおけるDiditの役割がなくなるわけではありません。生体認証に特有の規制がある法域で事業を行う場合は、ローンチ前に弁護士と実装内容を確認してください。

承認

x-api-key
string
header
必須

お客様のアプリケーションのAPIキーです。Business ConsoleのDevelopers -> API keysで取得できます。プライマリキーはフルアクセス権を持ちます。名前付きキーにはスコープを設定できます。リソースごとのアクセス権(なし、読み取り、書き込み)、一部のワークフローまたは承認済みセッションへの限定、IPアドレスのリストへの限定、有効期限の設定です。401は、キーが誤っている、失効している、または期限切れであることを意味します。403は、キーが送信されていない、キーにこのリソースやアクションへのアクセス権がない、またはIPリスト外のアドレスからリクエストが送信されたことを意味します。セッションのルートでの404は、セッションがキーのワークフローまたはステータスの対象外であることを意味します。メディアへのアクセス権がないキーでは、画像、動画、PDFのURLがnullで返されます。セッションの書き込み権限がないキーでは、セッションのリンクとトークンがnullで返されます。詳細は次を参照してください: https://docs.didit.me/console/api-keys

ボディ

application/json
workflow_id
string<uuid>
必須

セッションで実行する認証ステップを定義するワークフローの不変の識別子。ワークフローはコンソールのワークフローページで作成・管理します。workflow_idによって、セッションがKYCかKYBかも暗黙的に決まります。

例:

"11111111-2222-3333-4444-555555555555"

vendor_data
string

認証対象のユーザーの一意の識別子(UUID、メールアドレス、社内ユーザーIDなど)。このフィールドは次の用途に使用されます。(1) ユーザーのグループ化: 同じvendor_dataを持つセッションは、Usersタブで同じユーザープロフィールに紐付けられます。(2) セッション間の重複検出: 重複する顔、書類、電話番号、メールアドレス、IPアドレス、デバイスフィンガープリントを確認する際、同じvendor_dataを持つセッションは同一ユーザーとして扱われ、一致の対象から除外されます。vendor_dataがない場合、すべてのセッションが別々のユーザーとして扱われ、重複の可能性があるものがすべて表示されます。重複検出のノイズを減らすため、常にvendor_dataを指定することを強く推奨します。

例:

"user-123"

multi_account_segment
string

組織内で重複検知を行う任意の領域(レルム)です。重複顔チェックでは、このセッションを同じセグメントを持つ他のセッションとのみ比較します。そのため、別々のアカウント基盤(個人アカウントと法人アカウント、またはB2Bのサブクライアントごと)でそれぞれ1つずつ正当にアカウントを持つ人物がフラグ付けされることはありません。省略すると単一のデフォルト領域が使用されます。現在はすべてのセッションがこの領域を使用しています。ブロックリストと許可リストの照合では、このフィールドは無視されます。

Maximum string length: 64
例:

"business-accounts"

callback
string

認証完了後にユーザーをリダイレクトするURL。DiditはverificationSessionIdとstatus(Approved、Declined、In Review)をクエリパラメーターとして自動的に付加します。モバイルのコールバックにはカスタムURLスキーム(例: myapp://)を使用できます。省略した場合は、ワークフローのデフォルトのcallback_urlが使用されます。アプリケーションに許可ドメイン(PATCH /v3/webhook/のallowed_domains)が設定されている場合、httpまたはhttpsのコールバックはそのいずれかのオリジン(同一のスキーム、ホスト、ポート)上にある必要があります。そうでない場合、リクエストはcallbackについて400で失敗します: callback must be on one of the application's allowed domains: https://app.example.com。カスタムURLスキームは常に受け付けられます。

例:

"https://example.com/verification/callback"

callback_method
enum<string>
デフォルト:initiator

指定したコールバックURLへのリダイレクトを、どのデバイスで処理するかを決定します。フローを開始したデバイスのみをリダイレクトするにはinitiator、フローを完了するデバイスをリダイレクトするにはcompleter、どちらのデバイスでもコールバックをトリガーできるようにするにはbothを使用します。コールバックが確実にトリガーされない場合は、この値をbothに設定することをおすすめします。

利用可能なオプション:
initiator,
completer,
both
例:

"both"

metadata
any

セッションとともに保存され、レスポンスとWebhookでそのまま返される任意のJSON。任意のJSON値(オブジェクト、文字列、数値、配列)を受け付けますが、キーと値のペアからなるJSONオブジェクトを推奨します。エンドユーザーには表示されません。独自の相関ID、A/Bテストのバリアント、ビジネス上のコンテキストを渡すために使用します。

例:
tags
string[]

セッション作成時に名前で付与するタグ。最大10個、各50文字以内です。名前は大文字と小文字を区別せず、大文字で保存されます。アプリケーションにまだ存在しない名前は、新しいタグとして作成されます。タグはコンソールのセッションに表示され、タグでフィルターできます。

Maximum array length: 10
Maximum string length: 50
例:
language
enum<string>

認証プロセスのインターフェースの言語コード(ISO 639-1)。認証中にエンドユーザーに表示される言語を指定します。指定しない場合、ブラウザの言語が自動的に検出されて使用されます。対応言語の一覧はこちらで確認してください。

利用可能なオプション:
en,
ar,
bg,
bn,
bs,
ca,
cnr,
cs,
da,
de,
el,
es,
et,
fa,
fi,
fr,
he,
hi,
hr,
hu,
hy,
id,
it,
ja,
ka,
kk,
ko,
ky,
lt,
lv,
mk,
mn,
ms,
nl,
no,
pl,
pt-BR,
pt,
ro,
ru,
sk,
sl,
so,
sq,
sr,
sv,
th,
tr,
uk,
uz,
vi,
zh-CN,
zh-TW,
zh
例:

"en"

contact_details
object

通知、認証フォームの事前入力、電話番号検証に使用できるユーザーの連絡先情報。メールアドレス、連絡に使用する希望言語、電話番号が含まれます。

例:
expected_details
object

ユーザーの身分証明書類、住所証明、その他の検証ステップから抽出されたデータとの照合に使用される、想定されるユーザー情報です。不一致は判定上の警告として示されます。一部のフィールド(例: id_country、expected_document_types)は、ユーザー向けのフローも変更します。法人確認 (KYB)ワークフローでは企業フィールド(company_name、registry_country、registration_number)のみが使用され、ユーザー向けの法人登記検索に事前入力されます。個人レベルのフィールドはすべて無視されます。

例:
portrait_image
string<byte>

エンドユーザーの顔のBase64エンコードされたポートレート画像です(最大2MB、JPEG、PNG、WebPまたはTIFF)。ワークフローが顔照合を有効にしたBiometric Authenticationワークフローである場合、または本人確認(OCR)の前に顔照合を実行するグラフワークフローの場合に、ライブネスのキャプチャと照合する参照画像として使用されます。vendor_dataのユーザーに保存済みの顔画像がある場合は任意です。Diditはその顔画像を自動的に再利用し、次の優先順位で決定します: 承認済みのライブネスの顔、ePassportのチップ写真、身分証明書の顔写真、手動で登録したプロフィールの顔(承認済みセッションの顔、またはお客様自身が登録した顔のみが再利用されます)。portrait_imageを指定した場合は、常に保存済みの顔よりも優先されます。省略した場合に保存済みの顔が存在しないとき(またはvendor_dataを送信していないとき)は、セッションの作成が400で失敗します。その他のワークフロータイプでは無視されます。

例:

"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII="

sandbox_scenario
string

サンドボックス専用のシナリオスラッグです。APIキーがサンドボックスモードのアプリケーションに属する場合にのみ受け付けられ、本番環境のアプリケーションでは拒否されます。設定すると、作成フローはシナリオに同梱されたマジック値をセッションの入力フィールド(contact_details、expected_details)に展開し、モック化されたプロバイダーが実際のワークフローパイプラインを通じてシナリオの結果を再現します。シナリオカタログはGET /v1/sandbox/scenarios/またはサンドボックスとテストデータを参照してください。セッションがまだNot Startedである限り、作成後にPOST /v3/session/{sessionId}/sandbox/arm/でシナリオを有効化(または再有効化)することもできます。書類以外の照会では、lookup_partial_match、lookup_no_match、またはlookup_provider_errorを使用して、設定された試行回数の上限とフォールバックをテストできます。IDウォレットでは、wallet_cancelled、wallet_timeout、またはwallet_provider_errorを使用します。approveは検証済みのウォレットをシミュレートします。カタログのすべてのウォレットは、本番環境のアプリケーションでは利用できないスキームも含め、サンドボックスでテストできます。シミュレートされた試行は課金されません。

例:

"decline_document_expired"

sign
object

このセッションの電子署名の入力。documentsは署名対象の書類で、電子署名ステップがセッションから書類を取得するワークフロー(signature_documents_sourceがsessionまたはboth)で使用します。最大20件、合計50MBまでです。field_valuesは、prefillがapi.<key>であるフィールドに値を入力します。ワークフローの書類とセッションの書類のどちらにも適用されます。同じworkflow_idとvendor_dataでセッションを再度作成すると、保留中のセッションが返されます。その呼び出しでsignを送信する場合、書類、フィールド、値は最初のものと同一でなければならず、異なる場合は{"sign": "signature_document_changed"}とともに400が返されます。電子署名の書類を参照してください。

user_state
string

判明している場合の、本人の居住地です。ISO 3166-2の地域区分コード(US-IL、ES-M)、または米国の州コードもしくは州名(IL、Illinois)を指定します。明示的な生体認証の同意を法律で義務付けている州(イリノイ州、テキサス州、コロラド州)の場合、検証フローは顔を撮影する前に同意を求め、トリガーはdeclared_stateとなります。認識されない値は400を返します。生体認証の同意を参照してください。

Maximum string length: 16
例:

"US-IL"

本人からすでに取得済みの、生体認証に関する明示的な同意です。この要件を満たすため、認証フローで再度確認されることはなく、判定にはstatus: "given"、トリガーcustomer_collectedとして記録されます。本人がフロー内ですでに回答した内容が置き換えられることはありません。生体認証の同意を参照してください。

レスポンス

セッションが作成されました(ワークフローの最新公開バージョンに同じvendor_dataの未完了セッションが既に存在する場合は、そのセッションが返されます)。レスポンスはシリアライズされたセッションで、ユーザーのリダイレクト先となるホスト型検証ページのurlを含みます。

session_id
string<uuid>
必須

認証セッションの一意の識別子。GET /v3/session/{sessionId}/decision/を呼び出す際にこのIDを使用します。

例:

"11111111-2222-3333-4444-555555555555"

session_number
integer
必須

アプリケーション内でセッションに割り当てられる、人が読みやすい連番。サポートやダッシュボードで役立ちます。

例:

43762

session_token
string
必須

urlのホスト型検証フローへのアクセスをエンドユーザーに許可する、12文字のURLセーフなトークン。セッションの有効期限まで有効です。シークレットとして扱ってください。このトークンを持つ人は誰でも、このセッションの検証フローを開くことができます。

例:

"3FaJ9wLqX2Mz"

url
string<uri>
必須

エンドユーザーのリダイレクト先となるホスト型検証URLです。URLにはsession_tokenが埋め込まれ、設定されている場合はホワイトラベルドメインが使用されます。リクエストにlanguageが含まれる場合、URLには言語のパスセグメントが含まれます(https://verify.didit.me/{language}/session/{session_token}、例: /es/session/...)。languageがない場合、このセグメントは省略されます。

例:

"https://verify.didit.me/session/3FaJ9wLqX2Mz"

vendor_data
string | null
必須

自社システム内のユーザーまたは企業とセッションを紐付けるためにリクエストで渡した識別子。そのままの形で返されます。指定しなかった場合はnullです。

例:

"user-123"

metadata
any
必須

セッション作成時に保存した任意のJSONペイロード。そのまま返されます。送信したJSON値(オブジェクト、文字列、数値、配列)は変更されずに返されますが、JSONオブジェクトの使用を推奨します。エンドユーザーには表示されません。レスポンスには常に含まれ、作成時に指定しなかった場合はnullになります。

例:
status
enum<string>
必須

セッションの現在のステータス。新規作成されたセッションはNot Startedを返します。ワークフローの最新公開バージョンで同じvendor_dataの未完了セッションがすでに存在する場合、返されるステータスはその既存セッションのものです。

利用可能なオプション:
Not Started,
In Progress,
Approved,
Declined,
In Review,
Expired,
Abandoned,
Kyc Expired,
Resubmitted,
Awaiting User
例:

"Not Started"

callback
string<uri> | null
必須

フローの完了後にユーザーが送られる最終的なリダイレクトURLです。DiditはこのURLに?verificationSessionId={session_id}&status={status}を付加します。リクエストで指定されていない場合は、ワークフローに設定されたコールバックURLが使用されます。どちらも設定されていない場合はnullです。アプリケーションに許可ドメインが設定されており、このURLがその範囲外のWeb URLである場合(例えば、リストが変更される前に設定されたワークフローのデフォルト)、ホスト型フローはユーザーをこのURLにリダイレクトしません。

例:

"https://example.com/verification/callback"

workflow_id
string<uuid>
必須

このセッションが実行されるワークフローの不変の識別子。常にワークフローの不変のグループ識別子です。リクエストで特定のワークフローバージョンのUUIDを参照した場合(後方互換の検索)でも、レスポンスには不変のworkflow_idが含まれます。コンソールで設定したワークフローとセッションを関連付けるために使用します。

例:

"11111111-2222-3333-4444-555555555555"

workflow_version
integer
必須

セッション作成時に固定された、公開済みワークフローバージョンのバージョン番号。Diditはセッション作成時にworkflow_idをワークフローの最新の公開バージョンに解決し、後でワークフローが再公開された場合でも、セッションはそのバージョンで実行され続けます。

例:

3

tags
string[]

セッションに付いているタグ。名前で示されます。

例:
最終更新日 2026年11月1日