---
title: "Search Companies"
method: POST
path: "/v1alpha2/companies:search"
tags: ["ClientService"]
---

# Search Companies

`POST /v1alpha2/companies:search`

## Request

- Base URL: `https://api.thirdfort.dev/client/api`
- URL: `https://api.thirdfort.dev/client/api/v1alpha2/companies:search`
- Auth: HTTP bearer

Searches for companies by name or registration number within a jurisdiction. Returns a list of matching companies from external data providers.

## Request body

- SearchCompaniesRequest: Request message for [ClientService.SearchCompanies](#/operations/ClientService_SearchCompanies).
  - `jurisdiction` string, required: Required. The jurisdiction (country) to search in. Must be a valid ISO 3166-1 alpha-2 country code (e.g., "GB", "US").
  - `name` string: The company name to search for.
  - `registrationNumber` string: The company registration number to search for.
  - `dunsNumber` string: The DUNS number to search for. When set, the result is a single company looked up by its globally unique D&B identifier — used to resolve a registration number for downstream KYB-to-KYB checks.
  - `pageSize` integer: Optional. The maximum number of companies to return. If not specified, a default value of 10 will be used. The maximum value is 100; values above 100 will be coerced to 100. Not yet implemented: the field is accepted and ignored, a maximum of 10 results are returned in a single page.
  - `pageToken` string: Optional. A page token, received from a previous `SearchCompanies` call. Provide this to retrieve the subsequent page. Not yet implemented: the field is accepted and ignored.
  - `state` string: Optional. The state or region within the jurisdiction to refine the search. For US, this must be a 2-character state/province code (e.g., "CA", "NY", "ON").

## Response `200`

A successful response.

- SearchCompaniesResponse: Response message for [ClientService.SearchCompanies](#/operations/ClientService_SearchCompanies).
  - `companies` CompanyMatch[]: The list of matching companies.
    - `dunsNumber` string: The DUNS number for the company.
    - `name` string: The primary name of the company.
    - `jurisdiction` string: The jurisdiction (country) of the company. ISO 3166-1 alpha-2 country code.
    - `state` string: The state or region within the jurisdiction, if applicable. For US companies, this is the 2-character state code (e.g., "CA", "NY").
    - `registrationInfo` CompanyRegistrationInfo[]: All registration info associated with the company.
      - `registrationNumber` string: The registration number value.
      - `typeDescription` string: A description of the registration number type (e.g., "COMPANIES REGISTRY OFFICE Number (GB)", "VAT Number").
    - `operatingStatus` string: The operating status of the company (e.g., "Active", "Inactive").
    - `address` Typev1alpha2Address: A structured representation of an address. The format of this is designed to accomodate for address formats across the world, but may not be suitable for all countries currently.
      - `subBuilding` string
      - `buildingNumber` string: One of building_number or building_name must be provided.
      - `buildingName` string: One of building_number or building_name must be provided.
      - `street` string: Must be provided if building_number is set.
      - `subLocality` string
      - `locality` string
      - `administrativeArea` string
      - `postalCode` string
      - `countryCode` string
      - `company` string
  - `nextPageToken` string: A token to retrieve the next page of results. Pass this value in the page_token field in the subsequent call to `SearchCompanies`. If this field is omitted, there are no subsequent pages.

## Other responses

- `default`: An unexpected error response.

---

[API](https://skmtc.dev/thirdfort/apis/thirdfort-client-api-preview.md) - [All operations](https://skmtc.dev/thirdfort/apis/thirdfort-client-api-preview/llms.txt) - [OpenAPI document](https://skmtc.dev/thirdfort/apis/thirdfort-client-api-preview/revisions/3446b9aefa90?raw)