メインコンテンツへスキップ
POST
curl
このエンドポイントを最初に使用して、一致する法人登記の候補を検索します。 検索では、保存されるManual Checkは作成されません。 有料の企業データソースを使用したスタンドアロン検索が成功した場合、候補の件数にかかわらずリクエスト1件あたり$0.50の料金がかかります。結果が空の場合、検索に失敗した場合、および他のソースのみから結果が返された場合は課金されません。その後のプロフィール取得は別途請求されます。 有料ソースを使用する可能性がある検索では、Diditは登記情報に問い合わせる前に、該当する検索料金を確認して確保します。 残高が不足している場合は、code: "insufficient_credits"とともに403が返されます。 契約による請求では、合意済みの検索料金が適用されます。契約料金が設定されていない場合、検索は実行前に拒否されます。 サンドボックスでの検索は無料です。 成功した検索を繰り返すと、そのたびに新たな課金対象リクエストとなります。コールバックの配信によって検索料金が追加されることはありません。 webhook_urlを送信すると、プロバイダーが検索を処理している間にDiditはすぐにレスポンスを返し、候補の準備ができた時点で、候補をコールバックURLに送信できます。このコールバックは設計上署名されないため、この検索通知のためにWebhookシークレットを設定する必要はありません。検索コールバックのペイロード例を参照してください。 正しいkyb_response_idを選んだら、POST /v3/kyb/select/(Lite)、POST /v3/kyb/shareholders/またはPOST /v3/kyb/ubo/を呼び出し、必要なレベルで課金対象の登記プロフィールを取得します。
各候補のfetch_statusは検索時点ではpendingで、その候補を選択するまでpendingのままです。検索は候補を一覧表示するだけで、完全なプロフィールを取得するのは候補の選択です。状態が確定するのを待って検索をポーリングしないでください。kyb_response_idは、1回の検索リクエストに限定された不透明かつ一時的なハンドルです。受け取った値をそのまま指定し、絶対に解析したり内容から何かを導き出したりしないでください。また、同じ検索を繰り返すと新しいIDが返されることを前提としてください。検索後は速やかに候補を選択し、企業自体の安定した識別子が必要な場合はregistration_numberを使用してください。

検索レベル

tierは、検索を実行するプロバイダーチェーンの登記レベルを選択します。値はbasic(デフォルト、Liteチェーン)、shareholdersまたはuboです。候補一覧はそのレベルのチェーンから取得され、Lite検索が参照するソースと同じとは限りません。そのため、Lite検索の結果が空でも、登記情報にその企業が存在しないことの証明にはなりません。必要なレベルで再度検索してください。 指定したレベルを国が提供していない場合、検索はその国が提供する、指定レベル以下で最も高いレベルで実行されます。登記データがまったくない国は登記チェックの対象として提供されません。企業情報の手動入力で続行してください。 購入する予定のレベルで検索し、その候補を購入するエンドポイントから候補を取得します。

search_type

search_typeはcontainsのみを受け付け、これがデフォルトです。検索に使用される法人登記の情報源は企業名を部分一致で照合するため、start_withとfuzzyは暗黙的にcontainsとして扱われるのではなく、400("start_with" is not a valid choice)で拒否されます。企業を完全一致で照合するにはregistration_numberを送信してください。

ホスト型検索とスタンドアロン検索

POST /v1/kyb/search/は、ホスト型の検証フローが実行する検索です。認証は検証セッションによって行われ、APIキーに対しては403を返し、tierは受け付けません。チェーンはワークフローのKYB法人登記の設定によって選択されます。スタンドアロンAPIでは、x-api-keyを使用してPOST /v2/kyb/search/またはPOST /v3/kyb/search/を呼び出します。スタンドアロンの連携では、tierの入力とレベル別の選択用エンドポイントを使用して、必要なレベルで同じ候補にアクセスします。

登記情報プロバイダーの障害への対応

登記情報プロバイダーが一時的に利用できない場合、エンドポイントは機械判読可能な固定コードとともに502を返します。
このコードを受け取った場合は、ユーザーに企業情報の手動入力で続行させるか、後で再試行するよう依頼してください。バリデーションエラーは区別して扱ってください。無効な検索入力に対しては400が返され、この障害コードは使用されません。

非対応国と検索上限への対応

次の2つの固定コードは、再試行をやめて企業情報の手動入力で続行すべきことを示します。 ホスト型フローでは、登記ステップごとに有料の企業データソースでの検索が3回まで可能です。 3回目の検索後は、申請者に手動入力する選択肢が提示されます。 企業ではなく商標登録である候補を選択すると、code: "kyb_registry_entry_not_a_company"とともに400が返されます。 代わりに検索結果から企業を選んでください。

承認

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
country_code
string
必須

検索する法人登記の国を示すISO 3166-1 alpha-2コード。例: GB。法人登記が州や省のレベルで運営されている場合は、ISO 3166-2の地域区分コードをXX-YYの形式で付加します。US-CAはカリフォルニア州の登記を検索します。米国の検索では常に地域区分の指定が必要で、USのみの指定は拒否されます。大文字と小文字は区別されず、大文字に正規化されます。

Maximum string length: 10
例:

"GB"

name
string

検索する会社名。nameまたはregistration_numberのいずれかが必須です。

Maximum string length: 255
例:

"Tesco"

registration_number
string

検索する登記番号。nameまたはregistration_numberのいずれかが必須です。

Maximum string length: 100
tier
enum<string>
デフォルト:basic

この検索を実行するプロバイダーチェーンの登記レベル。basic(デフォルト)はその国のLiteチェーンを検索し、shareholdersとuboはそのレベルの所有構造チェーンを検索します。所有構造チェーンは別の情報源である場合があるため、Lite検索で結果が空でも、登記所にその企業が存在しないことの証明にはなりません。指定したレベルを提供していない国では、そのレベルまでの範囲で提供されている最上位のレベルで検索されます。候補は、検索したレベルを提供するエンドポイントから取得してください: POST /v3/kyb/select/(Lite)、POST /v3/kyb/shareholders/またはPOST /v3/kyb/ubo/。

利用可能なオプション:
basic,
shareholders,
ubo
例:

"basic"

search_type
enum<string>
デフォルト:contains

法人登記検索で適用される名前照合方式です。受け付けられる値はcontainsのみです。検索の背後にあるどの法人登記ソースも前方一致モードやあいまい一致モードを提供していないため、start_withとfuzzyは400(not a valid choice)で拒否されます。

利用可能なオプション:
contains
vendor_data
string

この照会に対するお客様側の識別子です。そのまま返され、Webhookコールバックに含まれます。

metadata
object | null

自由形式のJSON。そのまま返され、Webhookコールバックにも含まれます。

webhook_url
string<uri>

検索を非同期モードに切り替えます。APIは即座にレスポンスを返し、候補リストの準備ができると、署名なしのkyb.registry_search.resolvedコールバックをこのURLにPOSTします。

Maximum string length: 500

レスポンス

検索を受け付けました。同期モードでは解決済みの候補リストが返されます。Webhookモードではすぐにレスポンスが返され(多くの場合search_status: "pending")、最終的なリストはkyb.registry_search.resolvedコールバックで配信されます。

request_id
string<uuid>

webhook_urlを指定した場合:保存された検索リクエストのID。kyb.registry_search.resolvedコールバックでrequest_idとして返されます。webhook_urlを指定しない場合:一時的な相関UUIDです(検索は保存されません)。

kyb_registry
object
vendor_data
string | null

送信したvendor_dataをそのまま返します。

metadata
object | null

送信したmetadataのエコー。

created_at
string<date-time>
最終更新日 2026年11月1日