KYB Check V2

KYB (Know Your Business) Check is a robust service designed to provide real-time access to official registry data from a wide range of countries and states. This service enables businesses to retrieve up-to-date and accurate information using company names or registration numbers, facilitating confident decision-making, regulatory compliance, and thorough due diligence.

What's New in Version 2 (V2):

Optimized Response Time: Our V2 endpoints are enhanced to deliver faster data retrieval, reducing latency and ensuring real-time responses to your requests.
Instant Data Availability: When performing a company search, V2 instantly returns available company data, providing immediate access to critical information. More detailed and updated data will be retrieved in the background through the new /v2/kyb endpoint via the GET method.
Improved Error Handling: V2 introduces more informative error messages and precise status codes, making it easier to diagnose and resolve potential issues.

This updated version streamlines the process, enhancing the overall efficiency and reliability of the KYB check service.

Requests

"Requests" refer to the different HTTP methods used to interact with the API. Each request includes details such as endpoint URLs, required parameters, headers, and the structure of the request body. These details are necessary to initiate communication with the API and ensure proper functionality. Examples of requests often include sample payloads and expected inputs for successful interactions.

Supported Countries Listing

Description:

"Supported Countries Listing" provides a comprehensive list of countries along with the states that fall under them, where specific services are available. Each entry includes the country name, the country or state code, and the supported services within that region. Countries that are covered state by state are returned as one entry per state, with a `state_name` key. This helps users identify both country-wide and state-specific eligibility for various compliance checks and verification processes.

Method Call: GET

API:

https://api.thekyb.com/v2/countries

GET /v2/countries HTTP/1.1
Host: api.thekyb.com
Content-Type: application/json
Accept: application/json
token: YOUR_SECRET_KEY

var requestHeaders = new Headers();
requestHeaders.append("Content-Type", "application/json");
requestHeaders.append("Accept", "application/json");
requestHeaders.append("token", "YOUR_SECRET_KEY");

var requestOptions = {
  method: "GET",
  headers: requestHeaders,
  redirect: "follow"
};

fetch("https://api.thekyb.com/v2/countries", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.thekyb.com/v2/countries',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Accept: application/json',
    'token: YOUR_SECRET_KEY'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import requests
import json

url = "https://api.thekyb.com/v2/countries"

payload={}
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'token': 'YOUR_SECRET_KEY'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

var axios = require("axios");

var config = {
  method: "get",
  url: "https://api.thekyb.com/v2/countries",
  headers: {
    'Content-Type': "application/json",
    'Accept': "application/json",
    'token': "YOUR_SECRET_KEY",
  },
};

axios(config)
  .then(function (response) {
    console.log(JSON.stringify(response.data));
  })
  .catch(function (error) {
    console.log(error);
  });

curl --location --request GET 'https://api.thekyb.com/v2/countries' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'token: YOUR_SECRET_KEY'

Company Search

Description:
This API enables users to search for companies using "company name" or "registration number" as search parameters. You must provide at least one of "name" or "registration_number". Both can be provided simultaneously to narrow results. You can use this API to search for companies in single country. It directly accesses and fetches data from the official registries of the selected country. Additionally, the "search_type" parameter allows further refinement of the search using values like "start_with", "contains" or "fuzzy" for companies filtering.

Method Call: POST

API:

https://api.thekyb.com/v2/kyb

Parameter	Description
name	Type: String Required: Yes (at least one of `name` or `registration_number`; both may be provided) Minimum: 3 characters Maximum: 128 characters. Description: Name parameter contains the name of the company that is being searched.This parameter requires a company name.
registration_number	Type: String Required: Yes (at least one of `name` or `registration_number`; both may be provided) Minimum: 1 character Maximum: 255 characters. Description: This parameter contains the registration number of the company that is being searched.
country_codes	Type: Array Required: Yes Description: This parameter enables you to search for companies in specific countries or states using their respective codes. For example, enter the country code `['gb']` to search in the United Kingdom, or `['us_oh']` to search in Ohio, United States. Note: Only one country or state can be searched at a time, allowing you to efficiently narrow down your search.
search_type	Type: String Required: No Default: contains Between: contains, start_with or fuzzy The search_type offers three distinct modes: `start with`, `contains`, and `fuzzy`. start_with: Returns a list of companies whose names begin with the characters entered by the user. For example, if you search for "Apple," the API will return companies whose names start with "Apple". contains: Searches for companies that have the provided keyword anywhere in their names. For example, searching for "tech" will return companies that include "tech" at any position in their name. fuzzy: Allows for approximate matches and handles minor misspellings in the search input. This search mode automatically adjusts for typos and close matches, ensuring relevant results are returned. For example, a search for "Mircrosoft" will still return a list of companies that includes "Microsoft".
ttl	Type: Integer Required: No Description: This parameter specifies the time-to-live (TTL) value in seconds for the KYB request, with a minimum of `60` in seconds and no defined maximum limit. If the request can be resolved before the TTL expires, the results will be delivered immediately. However, if the TTL is reached, the request will be finalized, and only the data received from the official registry up to that point will be provided. No further data will be available for this request in the future.

POST /v2/kyb HTTP/1.1
Host: api.thekyb.com
Content-Type: application/json
Accept: application/json
token: YOUR_SECRET_KEY

{
  "country_codes": ["gb"],
  "name": "Testing Company",
  "search_type": "contains"
}

var requestHeaders = new Headers();
requestHeaders.append("Content-Type", "application/json");
requestHeaders.append("Accept", "application/json");
requestHeaders.append("token", "YOUR_SECRET_KEY");

var payload = JSON.stringify({
  "country_codes": ["gb"],
  "name": "Testing Company",
  "search_type": "contains",
});

var requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: payload,
  redirect: "follow"
};

fetch("https://api.thekyb.com/v2/kyb", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.thekyb.com/v2/kyb',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
      "country_codes": ["gb"],
      "name": "Testing Company",
      "search_type": "contains"
  }',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Accept: application/json',
    'token: YOUR_SECRET_KEY'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import requests
import json

url = "https://api.thekyb.com/v2/kyb"

payload = json.dumps({
  "country_codes": [
    "gb"
  ],
  "name": "Testing Company",
  "search_type": "contains"
})
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'token': 'YOUR_SECRET_KEY'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

const axios = require("axios");
let data = JSON.stringify({
  "country_codes": ["gb"],
  "name": "Testing Company",
  "search_type": "contains",
});

let config = {
  method: "post",
  url: "https://api.thekyb.com/v2/kyb",
  headers: {
    'Content-Type': "application/json",
    'Accept': "application/json",
    'token': "YOUR_SECRET_KEY",
  },
  data: data,
};

axios(config)
  .then(function (response) {
    console.log(JSON.stringify(response.data));
  })
  .catch(function (error) {
    console.log(error);
  });

curl --location --request POST 'https://api.thekyb.com/v2/kyb' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'token: YOUR_SECRET_KEY' \
--data '{
      "country_codes": ["gb"],
      "name": "Testing Company",
      "search_type": "contains"
}'

Company Search Results

Description:
When a user performs a company search through the API, it retrieves matching companies from official registries based on the search criteria. For example, searching for "Testing Company" in the United Kingdom will return all registered companies with that name. The results are paginated, with the number of results per page controlled by the "limit" value. Users can specify the "page" number and "limit" in the request to navigate through the data associated with a specific kyb_request_id, enabling efficient handling of large datasets.

Method Call: GET

API:

https://api.thekyb.com/v2/kyb?kyb_request_id=KYB_REQUEST_ID&page=PAGE&limit=LIMIT

Parameter	Description
kyb_request_id	Type: String Required: Yes Description: This is the unique ID for the KYB request, generated when performing a "company search" request. You can obtain it from the `kyb_request_id` field in the `kyb_request` object of the "company search" response.
page	Type: String Required: No Default: 1 Description: Page attribute tells the page number of the retrieved result.The page number can be specified using the "page" query parameter.
limit	Type: String Required: No Default: 25 Description: The "limit" key refers to a parameter that allows users to specify the maximum number of results or records they want to receive from a request. This parameter is particularly useful when dealing with large datasets or when users only need a specific number of items from the API response. For example, if the API provides a paginated response with 100 records per page, a user can set the "limit" key to 10 if they only want to receive the first 10 results. This way, the API will return a subset of the data containing the first 10 records, making the response more focused and efficient.

GET /v2/kyb?kyb_request_id=KYB_REQUEST_ID&page=PAGE&limit=LIMIT HTTP/1.1
Host: api.thekyb.com
Content-Type: application/json
Accept: application/json
token: YOUR_SECRET_KEY

var requestHeaders = new Headers();
requestHeaders.append("Content-Type", "application/json");
requestHeaders.append("Accept", "application/json");
requestHeaders.append("token", "YOUR_SECRET_KEY");

var requestOptions = {
  method: "GET",
  headers: requestHeaders,
  redirect: "follow"
};

fetch(
  "https://api.thekyb.com/v2/kyb?kyb_request_id=KYB_REQUEST_ID&page=PAGE&limit=LIMIT ,
  requestOptions
)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.thekyb.com/v2/kyb?kyb_request_id=KYB_REQUEST_ID&page=PAGE&limit=LIMIT ,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Accept: application/json',
    'token: YOUR_SECRET_KEY'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import requests
import json

url = "https://api.thekyb.com/v2/kyb?kyb_request_id=KYB_REQUEST_ID&page=PAGE&limit=LIMIT

payload={}
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'token': 'YOUR_SECRET_KEY'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

var axios = require("axios");

var config = {
  method: "get",
  url: "https://api.thekyb.com/v2/kyb?kyb_request_id=KYB_REQUEST_ID&page=PAGE&limit=LIMIT ,
  headers: {
    'Content-Type': "application/json",
    'Accept': "application/json",
    'token': "YOUR_SECRET_KEY",
  },
};

axios(config)
  .then(function (response) {
    console.log(JSON.stringify(response.data));
  })
  .catch(function (error) {
    console.log(error);
  });

curl --location --request GET 'https://api.thekyb.com/v2/kyb?kyb_request_id=KYB_REQUEST_ID&page=PAGE&limit=LIMIT  \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'token: YOUR_SECRET_KEY'

Detailed Company Insights

Description:

"Detailed Company Insights" offers in-depth information about a company retrieved from official registries. This includes key details such as company name, registration number, status, type, and more. These insights help users assess the legitimacy and operational standing of a business, providing essential data for due diligence and compliance checks.
To obtain detailed information about a company, you need to access the endpoint provided below with the kyb_response_id. This kyb_response_id can be obtained from the kyb_response_id field in the kyb_responses of the Company Search Results.

Method Call: GET

API:

https://api.thekyb.com/v2/kyb/KYB_RESPONSE_ID

Parameter Description

kyb_response_id Required: Yes
Type: String
Description: A unique identifier for the KYB response associated with a specific company. This ID is essential for retrieving detailed company insights from the API. It can be obtained from the kyb_response_id field in the kyb_responses array of the Company Search Results, ensuring users can access relevant data for due diligence and compliance checks. You must provide the kyb_response_id in the URL parameter when making the API request.

Parameter	Description
kyb_response_id	Required: Yes Type: String Description: A unique identifier for the KYB response associated with a specific company. This ID is essential for retrieving detailed company insights from the API. It can be obtained from the `kyb_response_id` field in the `kyb_responses` array of the Company Search Results, ensuring users can access relevant data for due diligence and compliance checks. You must provide the `kyb_response_id` in the URL parameter when making the API request.

GET  /v2/kyb/KYB_RESPONSE_ID HTTP/1.1
Host: api.thekyb.com
Content-Type: application/json
Accept: application/json
token: YOUR_SECRET_KEY

var requestHeaders = new Headers();
requestHeaders.append("Content-Type", "application/json");
requestHeaders.append("Accept", "application/json");
requestHeaders.append("token", "YOUR_SECRET_KEY");

var requestOptions = {
  method: "GET",
  headers: requestHeaders,
  redirect: "follow",
};

fetch(
  "https://api.thekyb.com/v2/kyb/KYB_RESPONSE_ID",
  requestOptions
)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.thekyb.com/v2/kyb/KYB_RESPONSE_ID',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Accept: application/json',
    'token: YOUR_SECRET_KEY'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import requests
import json

url = "https://api.thekyb.com/v2/kyb/KYB_RESPONSE_ID"

payload={}
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'token': 'YOUR_SECRET_KEY'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

var axios = require("axios");

var config = {
  method: "get",
  url: "https://api.thekyb.com/v2/kyb/KYB_RESPONSE_ID",
  headers: {
    'Content-Type': "application/json",
    'Accept': "application/json",
    'token': "YOUR_SECRET_KEY",
  },
};

axios(config)
  .then(function (response) {
    console.log(JSON.stringify(response.data));
  })
  .catch(function (error) {
    console.log(error);
  });

curl --location --request GET 'https://api.thekyb.com/v2/kyb/KYB_RESPONSE_ID' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'token: YOUR_SECRET_KEY'

Responses

"Responses" provide detailed information about the result of an API request, including status codes, response bodies, and the accompanying data. They indicate whether the request was successful or encountered an error and include relevant messages or data in structured formats, typically JSON. Response examples often feature success messages, error details, and data relevant to the specific request made.

Supported Countries Listing

Description:
The "Supported Countries Listing" response provides an overview of countries where API services are available, including country names, codes, and the compliance services offered. This allows users to understand the geographical coverage of the API services.

API:

https://api.thekyb.com/v2/countries

Response:

{
  "error": false,
  "message": "countries fetched successfully",
  "data": [
      {
          "name": "botswana",
          "code": "BW",
          "services": ["kyb"]
      },
      {
          "name": "sudan",
          "code": "SD",
          "services": ["kyb"]
      },
      {
          "name": "united_states",
          "state_name": "alabama",
          "code": "US_AL",
          "services": ["kyb"]
      },
      ...
  ]
}

Response Parameters:

Parameter	Description
error	Indicates whether the operation was successful. A value of `false` means the service was executed without errors.
message	A brief message summarizing the outcome of the request, such as confirmation of successful data retrieval.
data	Type: Array of objects. The countries and states supported for KYB checks. A country covered state by state has one entry per state.
data.*.name	Type: String. The country name in lowercase, with spaces replaced by underscores (e.g., `"botswana"`, `"united_states"`).
data.*.code	Type: String. The code to use in `country_codes`. For a country it is the ISO 3166-1 alpha-2 code (e.g., `"BW"`). For a state it is the country code and state code joined by an underscore (e.g., `"US_AL"` for Alabama).
data.*.services	Type: Array of strings. The services available in the country or state. It is always an array (e.g., `["kyb"]`).
data.*.state_name	Type: String. Optional / Conditional. The state name in lowercase, with spaces replaced by underscores (e.g., `"alabama"`). Returned only for state entries.

Company Search

Description:
The "Company Search" response provides detailed information about the companies that match the search parameters. It returns a list of companies retrieved from the official registries of the selected country based on the search criteria provided.
Additionally, the response includes pagination information to handle cases where the search returns multiple results, offering details on the total number of records, pages, and current page data.

API:

https://api.thekyb.com/v2/kyb

Response:

{
    "error": false,
    "message": "service created successfully",
    "data": {
        "kyb_request": {
            "country_codes": [
                "GB"
            ],
            "registration_number": null,
            "reference_id": "YOUR_REFERENCE_ID",
            "search_type": "contains",
            "status": "pending",
            "services": [
                "kyb_check"
            ],
            "extensive_data": [],
            "name": "Testing Company",
            "kyb_request_id": "YOUR_KYB_REQUEST_ID"
        },
        "kyb_responses": [
            {
                "kyb_response_id": "YOUR_KYB_RESPONSE_ID_1",
                "country_code": "GB",
                "name": "Testing Company",
                "registration_number": "12345",
                "registration_date": "2022-08-22",
                "type": "Private limited Company",
                "status": "dissolved",
                "fetch_status": "pending"
            },
            {
                "kyb_response_id": "YOUR_KYB_RESPONSE_ID_2",
                "country_code": "GB",
                "name": "ALLOW INDEPENDENT ROAD-TESTING COMPANY LIMITED",
                "registration_number": "10852307",
                "type": "PRI/LTD BY GUAR/NSC (Private, limited by guarantee, no share capital)",
                "status": "active",
                "fetch_status": "pending"
            }
        ],
        "pagination": {
            "total": 2,
            "per_page": 25,
            "current_page": 1,
            "last_page": 1,
            "from": 1,
            "to": 2
        }
    }
}

Response Parameters:

Parameter	Description
error	Indicates the success of the operation. A value of `false` confirms that the service executed without errors.
message	A concise message summarizing the outcome of the request, confirming that the service was created successfully.
data.kyb_request	This object contains details about the specific KYB request initiated by the user.
data.kyb_request.kyb_request_id	A unique identifier assigned to the specific KYB request.
data.kyb_request.country_codes	An array of ISO 3166-1 alpha-2 country codes (e.g., "GB") specifying the countries in which the KYB check is conducted.
data.kyb_request.registration_number	The registration number of the company, which may be `null` if not applicable.
data.kyb_request.reference_id	A unique reference identifier assigned to the KYB request, used for tracking the specific request.
data.kyb_request.name	The name utilized to identify the company being queried.
data.kyb_request.search_type	Indicates the nature of the search (e.g., "contains"), providing clarity on how the search text is processed and matched against records.
data.kyb_request.status	The current status of the data retrieval process for the kyb request. `"status": "pending"` indicates that the request is still in progress. `"status": "resolved"` indicates request has been completed.
data.kyb_request.services	An array detailing the specific services requested (e.g., "kyb_check"), indicating the type of compliance checks to be performed.
data.kyb_request.extensive_data	An array of extensive-data options associated with the request; may be empty (`[]`).
data.kyb_responses	An array of company records matching the search criteria. `risk_level` and `verification_status` are not part of this response; they are returned by Company Search Results once the request is resolved.
data.kyb_responses.*.kyb_response_id	The unique identifier for each specific KYB response record, facilitating easy reference within the response array.
data.kyb_responses.*.country_code	The country code associated with the company record, indicating the country from which the information is retrieved.
data.kyb_responses.*.name	The officially registered name of the company as found in the corresponding registry, crucial for identification and compliance verification.
data.kyb_responses.*.registration_number	The unique registration number assigned to the company by the appropriate registry, serving as a primary identifier within regulatory systems.
data.kyb_responses.*.registration_date	Optional. Date the company was registered (`YYYY-MM-DD`) when provided by the registry; may be omitted for some results.
data.kyb_responses.*.type	The legal or registry-defined company type (e.g., `"Private limited Company"`, `"Ltd"`).
data.kyb_responses.*.status	The current legal status of the company (e.g., "active" for operational companies, "dissolved" for companies that are no longer legally registered).
data.kyb_responses.*.fetch_status	The current status of the data retrieval process for the company. `"fetch_status": "pending"` indicates that the company data is still in progress. `"fetch_status": "resolved"` indicates complete data of this company has been fetched.
data.pagination	Contains pagination details for the response data, essential for navigating through multiple records if available.
data.pagination.total	The total count of records available across all pages, helping users understand the overall dataset size.
data.pagination.per_page	The number of records returned per page (e.g., 25), guiding users on the volume of data they are viewing at one time.
data.pagination.current_page	Indicates the current page number of the response, assisting users in tracking their place in the pagination.
data.pagination.last_page	Represents the total number of pages available for the results, allowing users to see the extent of the dataset.
data.pagination.from	The starting index of the current page in the overall dataset, providing context for the records being viewed.
data.pagination.to	The ending index of the current page in the overall dataset, completing the range of records available in that specific view.

Company Search Results

Description:
The "Company Search Results" response provides detailed information about companies matching the search criteria. Each record includes key details such as registration number and status, aiding in the evaluation of the business's legitimacy.
The response also contains pagination information, including the total number of records, records per page, and the current page, facilitating efficient navigation through the results.

API:

https://api.thekyb.com/v2/kyb?kyb_request_id=KYB_REQUEST_ID&page=PAGE&limit=LIMIT

Response:

Company Search Results Response Data
{
    "error": false,
    "message": "request data fetching in progress",
    "data": {
        "kyb_request": {
            "kyb_request_id": "YOUR_KYB_REQUEST_ID",
            "country_codes": [
                "GB"
            ],
            "registration_number": null,
            "reference_id": "YOUR_REFERENCE_ID",
            "name": "Testing Company",
            "search_type": "contains",
            "status": "pending",
            "services": [
                "kyb_check"
            ],
            "extensive_data": []
        },
        "kyb_responses": [
            {
                "kyb_response_id": "YOUR_KYB_RESPONSE_ID",
                "country_code": "GB",
                "name": "Testing Company",
                "registration_number": "12345",
                "registration_date": "2022-08-22",
                "type": "Private Limited Company",
                "status": "active",
                "fetch_status": "pending",
                "extensive_data": [
                    "Officers",
                    "Financial Performance",
                    "Filing History"
                ]
            }
        ],
        "pagination": {
            "total": 1,
            "per_page": 25,
            "current_page": 1,
            "last_page": 1,
            "from": 1,
            "to": 1
        }
    }
}

Response Parameters:

Parameter	Description
error	Indicates the success of the operation. A value of `false` confirms that the service executed without errors.
message	Human-readable poll status; varies with processing state. `"request data fetching in progress"` while the KYB request is still pending. `"We are still processing and fetching detailed information"` for accounts with tax ID fast resolve enabled, while a request is still pending after a longer processing time. `"request data fetched successfully"` when request data has finished resolving. Prefer `data.kyb_request.status` and `data.kyb_responses.*.fetch_status` for program logic.
data.kyb_request	This object contains details about the specific KYB request initiated by the user.
data.kyb_request.kyb_request_id	A unique identifier assigned to the specific KYB request.
data.kyb_request.country_codes	An array of ISO 3166-1 alpha-2 country codes (e.g., "GB") specifying the countries in which the KYB check is conducted.
data.kyb_request.registration_number	The registration number of the company, which may be `null` if not applicable.
data.kyb_request.reference_id	A unique reference identifier assigned to the KYB request, used for tracking the specific request.
data.kyb_request.name	The name utilized to identify the company being queried.
data.kyb_request.search_type	Indicates the nature of the search (e.g., "contains"), providing clarity on how the search text is processed and matched against records.
data.kyb_request.status	The current status of the data retrieval process for the kyb request. `"status": "pending"` indicates that the request is still in progress. `"status": "resolved"` indicates request has been completed.
data.kyb_request.services	An array detailing the specific services requested (e.g., "kyb_check"), indicating the type of compliance checks to be performed.
data.kyb_request.extensive_data	An array of extensive-data options associated with the request; may be empty (`[]`).
data.kyb_responses	An array of company records matching the search criteria.
data.kyb_responses.*.kyb_response_id	The unique identifier for each specific KYB response record, facilitating easy reference within the response array.
data.kyb_responses.*.country_code	The country code associated with the company record, indicating the country from which the information is retrieved.
data.kyb_responses.*.name	The officially registered name of the company as found in the corresponding registry, crucial for identification and compliance verification.
data.kyb_responses.*.registration_number	The unique registration number assigned to the company by the appropriate registry, serving as a primary identifier within regulatory systems.
data.kyb_responses.*.registration_date	Optional. Date the company was registered (`YYYY-MM-DD`) when provided by the registry; may be omitted for some results.
data.kyb_responses.*.type	The legal or registry-defined company type (e.g., `"Private Limited Company"`, `"Ltd"`).
data.kyb_responses.*.status	The current legal status of the company (e.g., "active" for operational companies, "dissolved" for companies that are no longer legally registered).
data.kyb_responses.*.fetch_status	The current status of the data retrieval process for the company. `"fetch_status": "pending"` indicates that the company data is still in progress. `"fetch_status": "resolved"` indicates complete data of this company has been fetched.
data.kyb_responses.*.risk_level	Optional / Conditional. Risk level of the company: `"low risk"`, `"medium risk"`, `"high risk"` or `"unknown"` (lowercase, with a space). Returned only when `data.kyb_request.status` is `"resolved"`.
data.kyb_responses.*.verification_status	Optional / Conditional. Verification status of the company: `"verified"`, `"failed"` or `"unknown"`. Returned only when `data.kyb_request.status` is `"resolved"`.
data.kyb_responses.*.extensive_data	An array of available data modules for the company (e.g., `"Officers"`, `"Financial Performance"`, `"Filing History"`).
data.pagination	Contains pagination details for the response data, essential for navigating through multiple records if available.
data.pagination.total	The total count of records available across all pages, helping users understand the overall dataset size.
data.pagination.per_page	The number of records returned per page (e.g. 25), guiding users on the volume of data they are viewing at one time.
data.pagination.current_page	Indicates the current page number of the response, assisting users in tracking their place in the pagination.
data.pagination.last_page	Represents the total number of pages available for the results, allowing users to see the extent of the dataset.
data.pagination.from	The starting index of the current page in the overall dataset, providing context for the records being viewed.
data.pagination.to	The ending index of the current page in the overall dataset, completing the range of records available in that specific view.

Detailed Company Insights

Description:
The Detailed Company Insights response provides comprehensive information about a specific company retrieved from official registries. It includes crucial details such as the company name, registration number, status, type, and more. This data allows users to assess the legitimacy and operational standing of the business effectively.

API:

https://api.thekyb.com/v2/kyb/KYB_RESPONSE_ID

Sample Company Response:

Here you can conveniently download the sample company response for The KYB Sample Company.

Additionally, you can retrieve the response via an API. Simply company search for "The KYB Sample Company" with the registration number "kyb000000" in the "United Kingdom" using a search type that "starts with".

Response:

Detailed Company Insights Response Data
{
  "error": false,
  "message": "company data fetched successfully",
  "data": {
    "kyb_response_id": "",
    "kyb_request_id": "",
    "name": "",
    "registration_number": "",
    "registration_date": "",
    "status": "",
    "type": "",
    "country_code": "",
    "description": "",
    "incorporation_date": "",
    "industries": "",
    "tax_number": "",
    "dissolution_date": "",
    "inactive_date": "",
    "fetch_status": "",
    "risk_level": "",
    "verification_status": "",
    "company_aml_request_id": "",
    "company_aml_ongoing_monitoring": false,
    "company_aml_request_status": null,
    "company_aml_status": null,
    "last_updated_at": null,
    "people_network_detail": {},
    "meta_detail": {},
    "contacts_detail": [
      {
        "type": "",
        "value": "",
        "meta_detail": {}
      }
    ],
    "previous_names_detail": [
      {
        "company_name": "",
        "update_date": "",
        "meta_detail": {}
      }
    ],
    "documents_detail": [
      {
        "uid": "",
        "title": "",
        "date": "",
        "description": "",
        "document_code": "",
        "document_type": "",
        "document_url": "",
        "document_status": "",
        "document_requested": false,
        "price": "",
        "price_without_service_charges": "",
        "service_charges": "",
        "deliver_time": "",
        "document_not_found": false,
        "meta_detail": {},
        "previous_document_detail": {
          "previous_document_id": "",
          "uid": "",
          "requested_at": "",
          "submitted_at": "",
          "price": "",
          "price_without_service_charges": "",
          "service_charges": ""
        },
        "own_document_detail": {
          "own_document_id": "",
          "uid": "",
          "document_url": "",
          "submitted_at": "",
          "requested_at": ""
        }
      }
    ],
    "addresses_detail": [
      {
        "address": "",
        "type": "",
        "description": "",
        "meta_detail": {}
      }
    ],
    "announcements_detail": [
      {
        "date": "",
        "title": "",
        "description": "",
        "meta_detail": {}
      }
    ],
    "people_detail": [
      {
        "name": "",
        "status": "",
        "address": "",
        "postal_address": "",
        "designation": "",
        "appointment_date": "",
        "termination_date": "",
        "nationality": "",
        "email": "",
        "phone_number": "",
        "fax_number": "",
        "employment_status": "",
        "aml_request_status": "",
        "aml_status": "",
        "aml_request_id": "",
        "meta_detail": {},
        "similar_people": [
          {
            "name": "",
            "address": "",
            "designation": "",
            "nationality": "",
            "appointment_date": "",
            "termination_date": "",
            "meta_detail": {
              "occupation": "",
              "current_status": "",
              "date_of_birth": "",
              "company": {
                "name": "",
                "jurisdiction_code": "",
                "company_number": ""
              }
            }
          }
        ]
      }
    ],
    "beneficial_owners_detail": [
      {
        "name": "",
        "email": "",
        "status": "",
        "address": "",
        "designation": "",
        "postal_address": "",
        "phone_number": "",
        "fax_number": "",
        "appointment_date": "",
        "legal_authority": "",
        "legal_form": "",
        "nationality": "",
        "termination_date": "",
        "ceased_on": "",
        "employment_status": "",
        "aml_request_status": "",
        "aml_status": "",
        "aml_request_id": "",
        "meta_detail": {
          "natures_of_control": ""
        },
        "shares_detail": {
          "voting_min_shares": "",
          "voting_max_shares": "",
          "ownership_min_shares": "",
          "ownership_max_shares": ""
        }
      }
    ],
    "parent_companies": [
      {
        "entity_type": "",
        "name": "",
        "company_number": "",
        "jurisdiction_code": "",
        "country_name": "",
        "type": "",
        "country_flag": "",
        "meta_detail": {}
      }
    ],
    "branches": [
      {
        "entity_type": "",
        "name": "",
        "company_number": "",
        "jurisdiction_code": "",
        "start_date": "",
        "home_company_name": "",
        "home_company_jurisdiction_code": "",
        "home_company_number": "",
        "country_name": "",
        "state_name": "",
        "type": "",
        "status": "",
        "dissolution_date": "",
        "registration_date": "",
        "industries": "",
        "address": "",
        "country_flag": ""
      }
    ],
    "accounts_detail": {
      "last_account": "",
      "next_account": "",
      "due_by_date": ""
    },
    "confirmation_statement_detail": {
      "last_account": "",
      "next_account": "",
      "due_by_date": ""
    },
    "company_extra_detail": {},
    "identifiers": [
      {
        "identifier_type": "",
        "identifier_code": "",
        "identifier_number": ""
      }
    ],
    "capital_stock_information": [
      {
        "capital_class": "",
        "capital_number": "",
        "capital_per_value": "",
        "meta_detail": {}
      }
    ],
    "industries_detail": [
      {
        "code": "",
        "name": "",
        "description": "",
        "meta_detail": {
          "code_scheme_id": ""
        }
      }
    ],
    "ownership_structure": {
      "id": "",
      "name": "",
      "children": [
        {
          "name": "",
          "percentage": "",
          "active": false,
          "meta_detail": {}
        }
      ]
    },
    "financial_detail": {
      "total_capital": "",
      "fiscal_year": "",
      "fiscal_year_end": "",
      "fiscal_year_start": "",
      "fixed_assets": "",
      "total_net_assets": "",
      "currency": "",
      "financial_years": "",
      "annual_return_due_date": "",
      "financial_statement_due_date": "",
      "liability": "",
      "total_number_of_shares": "",
      "have_extensive_shareholding": "",
      "ordinary_shareholder_signatures": "",
      "has_more_than_one_class_of_share": "",
      "per_share_value": "",
      "key_figure_readings": [
        {
          "data": {
            "current": "",
            "graph_up": false,
            "last_year": "",
            "last_year_value": "",
            "status": ""
          },
          "type": ""
        }
      ],
      "insights": [
        {
          "type": "",
          "data_type": "",
          "figures": [
            {
              "key_figure": "",
              "data": [
                {
                  "year": "",
                  "value": ""
                }
              ]
            }
          ]
        }
      ]
    },
    "registries_detail": [
      {
        "name": "",
        "source_type": ""
      }
    ],
    "additional_detail": [
      {
        "type": "",
        "data": [
          {
            "key_1": "",
            "key_2": ""
          }
        ]
      }
    ]
  }
}

Response Parameters:

Parameter	Description
error	Indicates whether an error occurred during the request. A value of false means no errors were encountered.
message	A message summarizing the outcome of the request, typically indicating success or details about any errors.
data	The main data object returned in the response, containing relevant information pertaining to the company, such as company profiles, status updates, and other details retrieved from the search.
data.last_updated_at	Timestamp of the last update when available; otherwise `null`.
data.people_network_detail	Object containing people-network information; may be empty (`{}`).
data.company_extra_detail	Extra company detail object. Currently always an empty object (`{}`).
data.company_aml_request_id	Optional / Conditional. AML request ID. Returned only when an AML check has been run for the company; otherwise the key is left out.
data.company_aml_ongoing_monitoring	Optional / Conditional. Type: Boolean. Whether ongoing AML monitoring is turned on for the company. Returned only when an AML check has been run for the company.
data.company_aml_request_status	Optional / Conditional. AML request status. Returned only when an AML check has been run for the company; otherwise the key is left out.
data.company_aml_status	Optional / Conditional. AML status of the company. Returned only when `company_aml_request_status` is `"resolved"`; otherwise the key is left out.
data.risk_level	Risk level of the company: `"low risk"`, `"medium risk"`, `"high risk"` or `"unknown"` (lowercase, with a space). Empty (`""`) until the KYB request is resolved.
data.verification_status	Verification status of the company: `"verified"`, `"failed"` or `"unknown"`. Empty (`""`) until the KYB request is resolved.
data.accounts_detail	Optional / Conditional. Accounts summary (`last_account`, `next_account`, `due_by_date`). Returned only when the registry provides it; otherwise the key is left out.
data.confirmation_statement_detail	Optional / Conditional. Confirmation statement summary (`last_account`, `next_account`, `due_by_date`). Returned only when the registry provides it; otherwise the key is left out.
data.addresses_detail[].description	Address description (e.g., `"registered office address"`).
data.people_detail[].employment_status	Employment/appointment status of the person (e.g., `"active"`).
data.beneficial_owners_detail[].meta_detail.natures_of_control	Description of natures of control for the beneficial owner.
data.beneficial_owners_detail[].shares_detail	Object with shareholding details such as `voting_max_shares` and `ownership_max_shares`.
data.industries_detail[].meta_detail.code_scheme_id	Industry code scheme identifier (e.g., `"uk_sic_2007"`, `"eu_nace_2"`, `"isic_4"`). May be absent when `meta_detail` is an empty array.
data.documents_detail[].previous_document_detail	Optional. Details of the same document already requested before (`previous_document_id`, `uid`, `price`, `price_without_service_charges`, `service_charges`, `requested_at`, `submitted_at`). Returned only when such a document exists.
data.documents_detail[].own_document_detail	Optional. Details of the document you requested yourself (`own_document_id`, `uid`, `document_url`, `requested_at`, `submitted_at`). Returned only when that document has been delivered.

Requests​

Supported Countries Listing​

Company Search​

Company Search Results​

Detailed Company Insights​

Responses​

Supported Countries Listing​

Company Search​

Company Search Results​

Detailed Company Insights​

Requests

Supported Countries Listing

Company Search

Company Search Results

Detailed Company Insights

Responses

Supported Countries Listing

Company Search

Company Search Results

Detailed Company Insights