メインコンテンツへスキップ
POST
Python
このガイドでは、他のプロバイダーからDiditへデータを移行する際に、適切なインポート方法を選ぶ方法を説明します。顧客が「インポート」と呼ぶジョブには、異なる2種類があります。
  • 過去の検証作業をインポートする:完了済みのKYC、KYB、トランザクションモニタリング、またはワークフロールールの記録を再作成し、以前のプロバイダーでの履歴をDiditに表示します。POST /v3/session/imports/を使用します。
  • 運用データをインポートする:ユーザー、企業、プロフィールの顔画像、ブロックリストのエントリー、または許可リストのエントリーを作成し、Diditが今後のチェックで利用できるようにします。エンティティ、顔、リストの各APIを使用します。
検証インポートでは、KYCとKYBについてsession_type: "MIGRATED"の履歴レコードが作成されます。エンドユーザーへのメール送信、ホスト型フローへのユーザーのリダイレクト、元の検証の再実行はいずれも行いません。インポートされたレコードは、該当する場合、セッション一覧、エンティティのプロフィール、取引ビュー、GET /v3/session/{session_id}/decision/に表示されます。

使用すべきインポートの種類

今後のチェック用にユーザーまたは企業のプロフィールだけが必要な場合は、過去の認証セッションをインポートしないでください。ユーザーまたは企業のエンティティAPIを使用してください。以前のプロバイダーの判定、書類のフィールド、警告、またはエビデンスをDiditのコンプライアンス履歴として表示する必要がある場合は、POST /v3/session/imports/を使用してください。

各プロバイダーから移行できるデータ

Diditは正規形式のCSVまたはNDJSONファイルを受け付けるため、データをエクスポートして変換すれば、どのプロバイダーからでも移行できます。インポートの仕様は常にDiditの正規スキーマです。

移行の流れ

  1. インポートするのが履歴、プロフィール、顔、リスト、取引、ルールのどれかを決めます。
  2. 旧プロバイダーからのデータのエクスポートはご自身で行います。旧プロバイダーのAPIキーをDiditに送らないでください。
  3. プロバイダーのエクスポートを、対応するDiditの正規CSVまたはNDJSONテンプレートに変換します。
  4. 大規模な移行ではNDJSONを推奨します。また、個別に再試行できるファイルに分割してください。
  5. インポートジョブを作成し、進捗をポーリングします。
  6. 行エラーを取得し、失敗した行だけを修正して再試行します。すべてのインポートジョブは、自然な外部IDに対して冪等です。

インポートジョブを作成する

インポートジョブは、1回のmultipartリクエストで作成します。
スプレッドシートを使った小規模な移行にはCSVを、大規模な移行にはNDJSONを使用してください。100k+行の場合、NDJSONの方がストリーミング、分割、検証、再試行を行いやすくなります。 取引のインポートでは、workflow_idを省略します。

リクエストフィールド

レコードの追跡と重複排除の仕組み

データソースを指定するリクエストフィールドはありません。すべてのインポートでDiditの正規スキーマを使用します。インポートされた各レコードには、追跡用にmetadata.imported_from = "generic"が保存されます。 user_verificationとbusiness_verificationのインポートでは、アプリケーション内でexternal_idに基づいて行の重複が排除されるため、同じファイルのインポートを再試行しても重複は作成されません。transactionsのインポートでは、代わりにtransaction_idに基づいて重複が排除されます。

書類の写真、動画、セルフィーの証跡をインポートする

import_type=user_verificationの場合、以前のプロバイダーから元の書類の写真、書類撮影およびライブネス撮影の動画、セルフィー画像をインポートできます。 次の標準カラムを使用してください。 大規模な移行ではHTTPS URLを使用してください。Diditは各ファイルをダウンロードし、URLが安全であることを検証したうえでDiditが所有するコピーを保存し、インポートしたセッションに紐付けます。画像は圧縮され、動画はそのまま保存されます。小規模なインポートでは画像のインラインbase64も受け付けますが、動画は必ずURLで指定する必要があります。base64にすると動画1本あたりのサイズが約33%増え、ファイルごとのインポート上限をすぐに超えてしまうためです。 プロバイダーがホストするメディアURLを含むNDJSON行の例:
メディアに関する重要なルール:
  • URLはhttpsを使用する必要があります。
  • URLの解決先がプライベートIP、localhost、リンクローカル範囲、内部メタデータホストであってはなりません。
  • 画像はURLカラムまたはその*_base64代替カラムのどちらでも指定できます。両方が設定されている場合はbase64が優先されます。動画はURLのみで、*_video_base64カラムはありません。
  • 動画はmp4、webm、movのいずれかである必要があり、各動画のサイズは最大10 MBです。これより大きいファイルや動画以外のファイルは行エラーとして拒否されます。
  • Diditは接続および読み取りのタイムアウト、最大ファイルサイズを適用し、無限に再試行することはありません。
  • メディアのダウンロードに失敗した場合は行エラーとして記録されるため、残りのインポートは継続できます。
  • プロバイダーからメディアを入手できない場合は、これらのカラムを空のままにしてください。その場合でも、Diditは構造化された判定と書類のフィールドをインポートします。
  • インポートした画像と動画は、過去の記録をレビューするための証跡です。Diditはデフォルトでは、インポートした過去のメディアに対してOCR、ライブネス、書類不正の分析を再実行しません。

進捗を確認する

レスポンスにはstatus、import_type、total_rows、processed_rows、created_count、updated_count、skipped_count、failed_count、checkpoint_rowが含まれます。

行エラーをダウンロードする

各エラーにはrow_number、external_id、error、raw_rowが含まれるため、失敗した行だけを修正して再試行できます。

不正利用対策

POST /v3/session/imports/による過去データのインポートジョブは、デフォルトで無効になっています。これらのジョブは数百万行を処理し、メディアをダウンロードする可能性があるため、Diditが審査のうえ組織ごとにこの機能を有効にします。このガイドで扱う通常の運用データのインポート(ユーザーの作成、企業の作成、プロフィール用の顔画像のアップロード、顔のブロックリストのアップロード、リストエントリの追加)には、各エンドポイントの通常のAPIキーの権限、製品の利用可否、レート制限以外に、移行用の特別な有効化は必要ありません。 また、過去データのインポートジョブは分離されたワーカー上で実行され、ファイルサイズの上限、行数の上限、HTTPSのみのメディアURL、プライベートネットワークのURLのブロック、アプリケーションごとの実行中ジョブ数の上限、行ごとのエラー記録が適用されます。

標準ステータス

冪等性

Diditは、ユーザー認証と法人確認のインポートでexternal_idをインポートの冪等性キーとして使用します。このキーはアプリケーションごとに適用されます。取引のインポートでは、アプリケーションごとにtransaction_idを使用します。同じファイルを再試行すると、すでにインポートされた行はスキップされ、まだ処理されていない行が作成されます。

ユーザー、プロフィール顔画像、ブロックリストのインポート

完了済みの認証セッションを再作成しない場合は、次の方法を使用します。

ユーザープロフィールのインポート

POST /v3/users/create/、またはユーザーのインポートとエクスポートで説明しているBusiness ConsoleのCSVインポートでユーザーを作成します。これはVendorUserプロフィールの作成または更新のみを行います。認証セッション、KYC判定、書類レポート、警告、Webhook履歴は作成されません。 今後のチェックの前にDiditに顧客の存在を認識させたい場合や、display_name、タグ、メタデータなどのCRMのようなフィールドをバックフィルする必要がある場合に使用します。

信頼済みプロフィール顔画像のアップロード

ユーザーが存在する状態で、POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/を使用して信頼済みのプロフィール顔画像をアップロードします。これにより生体情報のエビデンスがユーザープロフィールに紐付けられ、重複検出と顔検索のためにインデックス化されます。 この操作では顔はブロックリストに登録されません。以前のKYCプロバイダーから得た信頼済みのプロフィール画像があり、今後のDiditのチェックでその画像と照合したい場合に役立ちます。

顔のブロックリストと許可リストのインポート

顔を直接ブロックまたは許可するには、顔タイプのリストに対してPOST /v3/lists/{list_uuid}/entries/face-upload/を使用します。Diditが顔エンベディングを抽出し、リストエントリーとして保存します。 既知の不正者の画像、許可リストに登録する信頼済みの顔、またはプロバイダーの不正リストの移行に使用します。顔が既存のDiditセッションに由来する場合は、reference_session_idを指定したPOST /v3/lists/{list_uuid}/entries/を使用することをおすすめします。Diditがセッションから適切な顔を抽出し、エントリーを元のセッションに紐付けます。

ユーザー、企業、書類、ウォレット、メール、電話番号、IP、デバイスのリストのインポート

顔以外のリスト値にはPOST /v3/lists/{list_uuid}/entries/を使用します。プロバイダーのブロックリスト、許可リスト、チャージバックリスト、ウォレットアドレス、既知のリスクの高いIPアドレス、デバイスフィンガープリント、書類番号、メールアドレス、電話番号、ユーザー、企業のインポートにはこの方法が適しています。

次のステップ

ユーザーのインポート

ユーザープロフィールを読み込み、信頼済みのプロフィール顔画像を紐付けます。

企業のインポート

KYBを実行する前に企業プロフィールを読み込みます。

プロフィール顔画像のアップロード

インポートしたユーザーに信頼済みの顔画像を紐付けます。

リストへの顔のアップロード

ブロックリストまたは許可リストに顔を追加します。

リストエントリーの作成

電話番号、メールアドレス、ウォレット、書類、IPアドレス、デバイス、ユーザー、企業をリストにインポートします。

レート制限

安全な移行ループと再試行を設計します。

承認

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

ボディ

import_type
enum<string>
デフォルト:user_verification

インポートする対象です。過去のユーザー認証セッション、過去の法人確認セッション、ワークフローのカスタムステータスルール、または過去のトランザクションモニタリング記録のいずれかです。

利用可能なオプション:
user_verification,
business_verification,
status_rules,
transactions
workflow_id
string<uuid>

インポートしたセッションまたはステータスルールを紐付けるワークフローのUUID。user_verification、business_verification、status_rulesでは必須です。transactionsでは省略してください。

source_format
enum<string>

任意。省略した場合はアップロードされたファイルの拡張子から推定されます。

利用可能なオプション:
csv,
ndjson
file
file

正規形式のCSVまたはNDJSONファイル。大規模なインポートにはNDJSONを使用してください。アップロードの最大サイズは25MBです(それより大きいファイルにはsource_file_urlを使用してください)。source_file_urlとは同時に指定できません。

source_file_url
string<uri>

ファイルアップロードの代替手段です。パブリックアドレスに解決されるHTTPSのURLである必要があります(プライベート/ループバックネットワークは拒否されます)。fileとは同時に指定できません。

source
enum<string>

providerを指定すると、他の本人確認プロバイダーからの移行になります。ファイルインポートの場合は省略してください。

利用可能なオプション:
file,
provider
provider
enum<string>

移行元。GET /v3/session/imports/providers/から取得します。sourceがproviderの場合は必須です。

利用可能なオプション:
sumsub,
jumio,
veriff,
onfido,
persona,
metamap,
socure,
idnow,
shufti,
idenfy,
ondato,
trulioo,
au10tix,
complycube,
other
credentials
object

credential_fieldsに記載されたフィールド名を持つ、プロバイダーの読み取り専用キーです。保存時は暗号化され、返されることはなく、インポート終了時に消去されます。multipartではJSON文字列として送信してください。

options
object
status_mapping
object

プロバイダーのデフォルトのステータスマッピング(ソースのステータスからDiditのステータスへの対応)に対する変更。Not FinishedとAbandonedはスキップされてカウントされ、インポートされることはありません。

dry_run
boolean
デフォルト:false

移行でインポートされる件数(ステータス別、Didit登録済み、同一人物、未完了)を集計し、何も書き込みません。ジョブはREADYで終了します。POST /v3/session/imports/{importId}/start/で開始してください。

face_templates
boolean
デフォルト:false

インポートしたセルフィーから顔テンプレートを作成し、アプリケーションの顔とブロックリストに対して検索します。一致した場合はレビュー対象としてフラグが付けられるだけです。lawful_basis_confirmedが必要です。

lawful_basis_confirmed
boolean
デフォルト:false

処理者であるDiditとこれらのセルフィーを共有する法的根拠があることを確認します。

レスポンス

インポートジョブを受け付けました。statusがCOMPLETEDまたはFAILEDになるまで、返されたuuidをポーリングしてください。

uuid
string<uuid>
必須

インポートジョブのID。この値を使用して進捗をポーリングし、行ごとのエラーを取得します。

status
enum<string>
必須
利用可能なオプション:
PENDING,
PROCESSING,
COMPLETED,
FAILED,
PAUSED,
CANCELLED,
READY
import_type
enum<string>
必須
利用可能なオプション:
user_verification,
business_verification,
status_rules,
transactions
source_format
enum<string>
必須
利用可能なオプション:
csv,
ndjson
source_filename
string
必須
total_rows
integer<int64>
必須
processed_rows
integer<int64>
必須
created_count
integer<int64>
必須
updated_count
integer<int64>
必須
skipped_count
integer<int64>
必須
failed_count
integer<int64>
必須
checkpoint_row
integer<int64>
total_media_bytes
integer<int64>
last_error
string | null
created_at
string<date-time>
updated_at
string<date-time>
started_at
string<date-time> | null
completed_at
string<date-time> | null
state
enum<string>

コンソールに表示されるジョブの状態です。errorsは、拒否された行がある完了済みのジョブを表します。

利用可能なオプション:
ready,
queued,
running,
paused,
completed,
errors,
failed,
cancelled
source
enum<string>
利用可能なオプション:
file,
api,
provider
provider
string

移行元。ファイルまたはAPIによるインポートの場合は空です。

provider_options
object
credential_hint
string

移行が保持するキーの先頭の文字列です。キー自体が返されることはありません。

credentials_expires_at
string<date-time> | null
resumes_at
string<date-time> | null

プロバイダーのレート制限により一時停止したジョブが自動的に再開する日時。

status_mapping
object
is_dry_run
boolean
dry_run_summary
object

ドライランの結果: total、by_status、already_in_didit、same_person、not_finished、failed、unmapped_statuses。

face_templates_enabled
boolean
lawful_basis_confirmed_at
string<date-time> | null
not_finished_count
integer<int64>
same_person_count
integer<int64>
face_templates_count
integer<int64>
face_duplicates_count
integer<int64>
face_blocklist_hits_count
integer<int64>
created_by_name
string | null
created_by_email
string | null
最終更新日 2026年11月1日