> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # KYB法人登記検索API - 企業検索 > DiditのPOST /v3/kyb/search/は企業候補を検索します。有料の企業データソースでの検索成功はリクエスト1件あたり$0.50で、プロフィール取得は別途請求されます。 このエンドポイントを最初に使用して、一致する法人登記の候補を検索します。 検索では、保存されるManual Checkは作成されません。 有料の企業データソースを使用したスタンドアロン検索が成功した場合、候補の件数にかかわらず**リクエスト1件あたり\$0.50**の料金がかかります。結果が空の場合、検索に失敗した場合、および他のソースのみから結果が返された場合は課金されません。その後のプロフィール取得は別途請求されます。 有料ソースを使用する可能性がある検索では、Diditは登記情報に問い合わせる前に、該当する検索料金を確認して確保します。 残高が不足している場合は、`code: "insufficient_credits"`とともに`403`が返されます。 契約による請求では、合意済みの検索料金が適用されます。契約料金が設定されていない場合、検索は実行前に拒否されます。 サンドボックスでの検索は無料です。 成功した検索を繰り返すと、そのたびに新たな課金対象リクエストとなります。コールバックの配信によって検索料金が追加されることはありません。 `webhook_url`を送信すると、プロバイダーが検索を処理している間にDiditはすぐにレスポンスを返し、候補の準備ができた時点で、候補をコールバックURLに送信できます。このコールバックは設計上署名されないため、この検索通知のためにWebhookシークレットを設定する必要はありません。[検索コールバックのペイロード例](https://docs.didit.me/ja/standalone-apis/kyb-registry.md#検索コールバック)を参照してください。 正しい`kyb_response_id`を選んだら、`POST /v3/kyb/select/`(Lite)、`POST /v3/kyb/shareholders/`または`POST /v3/kyb/ubo/`を呼び出し、必要なレベルで課金対象の登記プロフィールを取得します。 > [!NOTE] > > 各候補の`fetch_status`は検索時点では`pending`で、その候補を選択するまで`pending`のままです。検索は候補を一覧表示するだけで、完全なプロフィールを取得するのは候補の選択です。状態が確定するのを待って検索をポーリングしないでください。 > > `kyb_response_id`は、1回の検索リクエストに限定された不透明かつ一時的なハンドルです。受け取った値をそのまま指定し、絶対に解析したり内容から何かを導き出したりしないでください。また、同じ検索を繰り返すと新しいIDが返されることを前提としてください。検索後は速やかに候補を選択し、企業自体の安定した識別子が必要な場合は`registration_number`を使用してください。 ## 検索レベル `tier`は、検索を実行するプロバイダーチェーンの登記レベルを選択します。値は`basic`(デフォルト、Liteチェーン)、`shareholders`または`ubo`です。候補一覧はそのレベルのチェーンから取得され、Lite検索が参照するソースと同じとは限りません。そのため、Lite検索の結果が空でも、登記情報にその企業が存在しないことの証明にはなりません。必要なレベルで再度検索してください。 指定したレベルを国が提供していない場合、検索はその国が提供する、指定レベル以下で最も高いレベルで実行されます。登記データがまったくない国は登記チェックの対象として提供されません。企業情報の手動入力で続行してください。 購入する予定のレベルで検索し、その候補を購入するエンドポイントから候補を取得します。 | 検索した`tier` | 候補を取得するエンドポイント | | - | - | | `basic`(デフォルト) | `POST /v3/kyb/select/`(Lite) | | `shareholders` | `POST /v3/kyb/shareholders/` | | `ubo` | `POST /v3/kyb/ubo/` | ## 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`を返します。 ```json theme={null} { "detail": "The company registry provider is temporarily unavailable.", "code": "kyb_registry_provider_unavailable" } ``` このコードを受け取った場合は、ユーザーに企業情報の手動入力で続行させるか、後で再試行するよう依頼してください。バリデーションエラーは区別して扱ってください。無効な検索入力に対しては`400`が返され、この障害コードは使用されません。 ## 非対応国と検索上限への対応 次の2つの固定コードは、再試行をやめて企業情報の手動入力で続行すべきことを示します。 | ステータス | `code` | 発生条件 | | - | - | - | | `400` | `kyb_registry_country_unsupported` | その国には、どのレベルにも法人登記のソースがありません。この制限は恒久的なため、同じ検索を再試行しても成功することはありません。 | | `429` | `kyb_registry_search_limit_reached` | アプリケーションが有料の企業データソースに対する1時間あたり600件の検索枠を使い切り、その国で利用できる無料ソースが残っていません。時間枠が経過するまで待つか、企業情報を手動で入力してください。 | ホスト型フローでは、登記ステップごとに有料の企業データソースでの検索が3回まで可能です。 3回目の検索後は、申請者に手動入力する選択肢が提示されます。 企業ではなく商標登録である候補を選択すると、`code: "kyb_registry_entry_not_a_company"`とともに`400`が返されます。 代わりに検索結果から企業を選んでください。 ## OpenAPI ````yaml ja/openapi-25.json POST /v3/kyb/search/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: 本人確認API。x-api-keyヘッダーで認証します。 servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/kyb/search/: post: tags: - Standalone APIs summary: KYB法人登記の企業検索（スタンドアロン） description: >- 会社名、登記番号、またはその両方で公式の法人登記を検索し、候補となる企業を取得します。これは2段階のレジストリフローのステップ1です。**検索**では軽量な候補が返され、続いて`POST /v3/kyb/select/`で候補1件の完全なプロファイルを取得します。 **検索の請求。** 有料の企業データソースを使用した検索が成功すると、候補の件数にかかわらずリクエスト1件あたりUSD 0.50が課金されます。結果が空の場合、失敗した場合、および他のソースのみから提供された結果には課金されません。該当する料金は検索前に確保されます。残高が不足している場合は、コード`insufficient_credits`とともに403が返されます。合意がある場合は契約料金が適用され、契約の検索料金が設定されていない場合は403が返されます。サンドボックスでの検索は無料です。成功した検索を繰り返すと、再度課金される場合があります。コールバックの配信による追加の課金はありません。プロファイルの取得は別途請求されます。この検索料金はv2にも適用されます。候補は常に`fetch_status: "pending"`で返されます。企業の完全なデータはselect時にのみ取得（および請求）されます。 **`kyb_response_id`は一時的なものです。** これは検索ごとのハンドルであり、安定した企業IDではありません。検索後は速やかにselectを実行してください。ハンドルを保存するのではなく、再検索して新しいハンドルを取得してください。 **`tier`でプロバイダーチェーンを選択します。** `tier`は検索を実行するレジストリのレベルを指定します。指定できる値は`basic`（デフォルト、Liteチェーン）、`shareholders`、`ubo`です。検索ではそのレベルを提供するプロバイダーチェーンが使用されますが、これはLite検索が参照するチェーンと常に同じとは限りません。そのため、Lite検索の結果が空であっても、レジストリにその企業が登録されていない証拠にはなりません。必要なレベルで再度検索してください。指定したレベルを提供していない国では、そのレベルまでの範囲で提供されている最も高いレベルで検索されます。候補は、そのレベルを提供するエンドポイントから取得してください。`POST /v3/kyb/select/`（Lite）、`POST /v3/kyb/shareholders/`、または`POST /v3/kyb/ubo/`です。 **認証。** `POST /v3/kyb/search/`（および`/v2/`）では、アプリケーションのAPIキーを`x-api-key`ヘッダーで渡します。ホスト型の`POST /v1/kyb/search/`は、ホスト型検証フローが呼び出すセッション認証のルートです。APIキーに対しては`403`を返し、`tier`は受け付けません。チェーンはワークフローのKYBレジストリ設定によって選択されます。 **2つのモード。** - *同期（デフォルト）：* APIは検索が完了するまでレジストリをポーリングし、最終的な候補リストを返します（`search_resolved: true`）。 - *非同期：* `webhook_url`を渡すと、APIはすぐにレスポンスを返します（通常は`search_status: "pending"`と空の候補リスト）。その後、レジストリの処理が完了すると、指定したURLに`kyb.registry_search.resolved`コールバックをPOSTします。コールバックの本文は`{"event_id", "event_type": "kyb.registry_search.resolved", "request_id", "vendor_data", "metadata", "search_status", "search_resolved", "kyb_registry", "timestamp", "created_at"}`です。コールバック内の`timestamp`と`created_at`は、このエンドポイントのISO形式の`created_at`とは異なり、エポック秒の整数である点に注意してください。また、コールバックは**署名なし**で送信されます（ヘッダー`X-Didit-Unsigned-Callback: true`、`X-Signature`なし）。 **国コード。** ISO 3166-1 alpha-2（`GB`、`DE`）に加え、レジストリが地域単位の場合は`XX-YY`形式の地域区分コードを使用します。例：カリフォルニア州は`US-CA`。 **サンドボックス。** サンドボックスアプリケーションのキーでは、どのレジストリにも接続せずに固定の候補が1件返されます。 operationId: post_v3_kyb_search parameters: [] requestBody: required: true content: application/json: schema: type: object required: - country_code properties: country_code: type: string maxLength: 10 description: >- 検索する法人登記の国を示すISO 3166-1 alpha-2コード。例: `GB`。法人登記が州や省のレベルで運営されている場合は、ISO 3166-2の地域区分コードを`XX-YY`の形式で付加します。`US-CA`はカリフォルニア州の登記を検索します。米国の検索では常に地域区分の指定が必要で、`US`のみの指定は拒否されます。大文字と小文字は区別されず、大文字に正規化されます。 example: GB name: type: string maxLength: 255 description: 検索する会社名。`name`または`registration_number`のいずれかが必須です。 example: Tesco registration_number: type: string maxLength: 100 description: 検索する登記番号。`name`または`registration_number`のいずれかが必須です。 tier: type: string enum: - basic - shareholders - ubo default: basic description: >- この検索を実行するプロバイダーチェーンの登記レベル。`basic`（デフォルト）はその国のLiteチェーンを検索し、`shareholders`と`ubo`はそのレベルの所有構造チェーンを検索します。所有構造チェーンは別の情報源である場合があるため、Lite検索で結果が空でも、登記所にその企業が存在しないことの証明にはなりません。指定したレベルを提供していない国では、そのレベルまでの範囲で提供されている最上位のレベルで検索されます。候補は、検索したレベルを提供するエンドポイントから取得してください: `POST /v3/kyb/select/`（Lite）、`POST /v3/kyb/shareholders/`または`POST /v3/kyb/ubo/`。 example: basic search_type: type: string enum: - contains default: contains description: >- 法人登記検索で適用される名前照合方式です。受け付けられる値は`contains`のみです。検索の背後にあるどの法人登記ソースも前方一致モードやあいまい一致モードを提供していないため、`start_with`と`fuzzy`は`400`（`not a valid choice`）で拒否されます。 vendor_data: type: string description: この照会に対するお客様側の識別子です。そのまま返され、Webhookコールバックに含まれます。 metadata: type: object nullable: true description: 自由形式のJSON。そのまま返され、Webhookコールバックにも含まれます。 webhook_url: type: string format: uri maxLength: 500 description: >- 検索を非同期モードに切り替えます。APIは即座にレスポンスを返し、候補リストの準備ができると、署名なしの`kyb.registry_search.resolved`コールバックをこのURLにPOSTします。 example: country_code: GB name: Tesco search_type: contains vendor_data: company-1234 responses: '200': description: >- 検索を受け付けました。同期モードでは解決済みの候補リストが返されます。Webhookモードではすぐにレスポンスが返され（多くの場合`search_status: "pending"`）、最終的なリストは`kyb.registry_search.resolved`コールバックで配信されます。 content: application/json: schema: type: object properties: request_id: type: string format: uuid description: >- `webhook_url`を指定した場合：保存された検索リクエストのID。`kyb.registry_search.resolved`コールバックで`request_id`として返されます。`webhook_url`を指定しない場合：一時的な相関UUIDです（検索は保存されません）。 kyb_registry: $ref: '#/components/schemas/KYBRegistrySearchResults' vendor_data: type: string nullable: true description: 送信した`vendor_data`をそのまま返します。 metadata: type: object nullable: true description: 送信した`metadata`のエコー。 created_at: type: string format: date-time examples: Resolved search: summary: '同期モード: 最終候補リスト' value: request_id: 0c7e9a40-3a13-4f7e-8a44-9d2e2f1c5b6a kyb_registry: companies: - kyb_response_id: 69aeeb95febb0f1704042259 name: Tesco PLC registration_number: '00445790' status: active type: Public Limited Company risk_level: null fetch_status: pending - kyb_response_id: 69aeeb95febb0f170404225a name: E-TESCO LTD registration_number: '15168476' status: active type: Private Limited Company risk_level: null fetch_status: pending pagination: total: 2 page: 1 per_page: 25 search_status: resolved search_resolved: true vendor_data: company-1234 metadata: null created_at: '2026-06-11T10:40:00.000000+00:00' Pending search (webhook mode): summary: >- `webhook_url`が指定されています。候補はkyb.registry_search.resolvedコールバックで届きます value: request_id: 5f2d8c1b-7e4a-4b9c-9f0d-3a6e8c2b1d4f kyb_registry: companies: [] pagination: total: 0 page: 1 per_page: 25 search_status: pending search_resolved: false vendor_data: company-1234 metadata: source: onboarding created_at: '2026-06-11T10:41:00.000000+00:00' '400': description: >- バリデーションエラー。フィールド単位の問題はDRFの標準エンベロープを使用します。名称/登記番号のルールは`non_field_errors`の下に報告されます。登記所が対応していない国の場合は、`code: kyb_registry_country_unsupported`とともに`400`が返されます。 content: application/json: examples: Missing search criteria: summary: '`name`と`registration_number`のどちらも指定されていません' value: non_field_errors: - Either 'name' or 'registration_number' is required. Invalid country_code: summary: '`XX`（alpha-2）または`XX-YY`の行政区画形式である必要があります' value: country_code: - country_code must be a 2-letter ISO code. Invalid search_type: summary: '`contains`のみ受け付けます' value: search_type: - '"start_with" is not a valid choice.' Invalid webhook_url: summary: '`webhook_url`は有効なURLである必要があります' value: webhook_url: - Enter a valid URL. Country not covered: summary: この国をカバーする法人登記はありません value: detail: >- Company registry search is not available for this country. Enter the company details manually to continue. code: kyb_registry_country_unsupported '403': description: >- 権限がありません。`x-api-key`ヘッダーがない場合に返されます。誤った、取り消された、または期限切れのキーの場合は`401`が返されます。キーがない場合は`{"detail": ...}`とともに`403`が返され、誤った、取り消された、または期限切れのキーの場合は`401`が返されます。また、該当する検索料金を賄えない場合（`code: "insufficient_credits"`）や、契約上の検索料金が設定されていない場合にも、検索前に返されます。 content: application/json: examples: Missing or invalid API key: summary: '`x-api-key`ヘッダーがないか、キーが無効または失効しています' value: detail: You do not have permission to perform this action. '429': description: >- レート制限を超過したか、検索の利用枠を使い切りました。すべてのPOST/PATCH/DELETEエンドポイントは、APIキーごとに1分あたり300件の書き込みリクエストという共通の上限を共有し、`X-RateLimit-*`および`Retry-After`ヘッダーが返されます。これとは別に、有料の法人登記検索はアプリケーションごとに1時間あたり600件に制限されています。これを超えるとレスポンスは`code: kyb_registry_search_limit_reached`を伴う`429`になりますが、無料ソースのみで処理される検索は引き続き利用できます。しばらく待ってから再度検索してください。 content: application/json: examples: Write rate limit exceeded: summary: 現在の1分間に300件を超える書き込みリクエスト value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. Search allowance spent: summary: 直近1時間に600件を超える有料検索 value: detail: >- The maximum number of company registry searches for this session has been reached. Enter the company details manually to continue. code: kyb_registry_search_limit_reached schema: type: object properties: detail: type: string code: type: string '502': description: >- KYB登記プロバイダーが一時的に利用できません（上流の登記機関からの5xxレスポンス、タイムアウト、または接続失敗）。この検索は課金されません。後で再試行してください。Diditのホスト型検証フローでは、再試行のみのエラーではなく、企業情報の手動入力がユーザーに自動的に提示されます。 content: application/json: examples: Registry provider outage: summary: 法人登記のプロバイダーが検索に応答しませんでした value: detail: >- The KYB registry provider is temporarily unavailable. Please try again shortly. code: kyb_registry_provider_unavailable schema: type: object properties: detail: type: string code: type: string security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: |- curl -X POST https://verification.didit.me/v3/kyb/search/ \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "country_code": "GB", "name": "Tesco", "search_type": "contains", "vendor_data": "company-1234" }' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.kyb.search( country_code="GB", name="Tesco", search_type="contains", vendor_data="company-1234", ) print(result) - lang: javascript label: Node.js source: |- import Didit from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.kyb.search({ country_code: "GB", name: "Tesco", search_type: "contains", vendor_data: "company-1234", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.KYB.Search(ctx, didit.KYBSearchParams{\n\tCountryCode: \"GB\",\n\tName: didit.String(\"Tesco\"),\n\tSearchType: didit.Some(didit.KYBSearchParamsSearchType(\"contains\")),\n\tVendorData: didit.String(\"company-1234\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: |- import me.didit.Didit; import me.didit.types.KybSearchParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.kyb().search(KybSearchParams.builder() .countryCode("GB") .name("Tesco") .searchType(KybSearchParams.SearchType.of("contains")) .vendorData("company-1234") .build()); System.out.println(result); - lang: php label: PHP source: |- kyb->search([ 'country_code' => 'GB', 'name' => 'Tesco', 'search_type' => 'contains', 'vendor_data' => 'company-1234', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.kyb.search( country_code: "GB", name: "Tesco", search_type: "contains", vendor_data: "company-1234" ) puts result.to_h - lang: csharp label: .NET source: |- using System; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.Kyb.SearchAsync(new KybSearchParams { CountryCode = "GB", Name = "Tesco", SearchType = new KybSearchParamsSearchType("contains"), VendorData = "company-1234", }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: KYBRegistrySearchResults: type: object properties: companies: type: array items: type: object properties: kyb_response_id: type: string nullable: true description: >- この候補のハンドルです。`POST /v3/kyb/select/`に渡すと完全なプロファイルを取得できます。一時的なもので、この検索にのみ有効です。長期保存はせず、新しいハンドルが必要な場合は再検索してください。 example: 69aeeb95febb0f1704042259 name: type: string nullable: true description: 登記されている企業名。 example: Tesco PLC registration_number: type: string nullable: true description: 登記番号。 example: '00445790' status: type: string nullable: true description: >- 正規化された企業の登記ステータス（例: `active`、`dissolved`、`inactive`、`struck off`）。 example: active type: type: string nullable: true description: 法人登記に記載された法人形態。 example: Public Limited Company registered_address: type: string nullable: true description: >- 登記所から返された場合の、候補の登記住所。登記番号と併せて使用し、同名の企業を区別してください。米国では、検索した州ではなく企業が事業を行っている州で候補が登録されている場合があります。 example: >- Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, AL7 1GA risk_level: type: string nullable: true description: 登記所が報告したリスクレベル（取得できる場合）。検索時点では通常`null`です。 fetch_status: type: string nullable: true description: 検索候補では常に`pending`です。企業の完全なプロファイルは、候補を選択したときにのみ取得（および課金）されます。 example: pending description: >- 重複を除いた候補リスト。`search_resolved=false`の間（Webhookモード）、または一致するものがない場合は空です。 pagination: type: object properties: total: type: integer description: 返された候補の数。 page: type: integer per_page: type: integer example: 25 search_status: type: string nullable: true enum: - pending - resolved description: 登記検索のライフサイクルステータス。 search_resolved: type: boolean description: 候補リストが確定すると`true`になります。 securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- お客様のアプリケーションのAPIキーです。Business ConsoleのDevelopers -> API keysで取得できます。プライマリキーはフルアクセス権を持ちます。名前付きキーにはスコープを設定できます。リソースごとのアクセス権（なし、読み取り、書き込み）、一部のワークフローまたは承認済みセッションへの限定、IPアドレスのリストへの限定、有効期限の設定です。401は、キーが誤っている、失効している、または期限切れであることを意味します。403は、キーが送信されていない、キーにこのリソースやアクションへのアクセス権がない、またはIPリスト外のアドレスからリクエストが送信されたことを意味します。セッションのルートでの404は、セッションがキーのワークフローまたはステータスの対象外であることを意味します。メディアへのアクセス権がないキーでは、画像、動画、PDFのURLがnullで返されます。セッションの書き込み権限がないキーでは、セッションのリンクとトークンがnullで返されます。詳細は次を参照してください: https://docs.didit.me/console/api-keys ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.