KYB Check

info

We are pleased to share KYB Check Version 2, which offers faster data retrieval, improved performance, and streamlined functionality for a smoother experience.
We recommend integrating KYB Check v2 to make the most of these enhancements in your compliance management.

Introducing the groundbreaking solution known as KYB Check, a service that offers real-time data retrieval from official registries. This service grants businesses immediate access to information sourced from the official registries of various countries and states.

By using this service, companies can easily collect accurate and up-to-date information by searching with company names or registration numbers. Unlike traditional methods that rely on outdated databases, this service ensures that the information is current and reliable. This empowers businesses to confidently make informed decisions. Whether verifying the credibility of potential partners, assessing compliance, or conducting due diligence, the KYB Check service offers a seamless and efficient way to utilize official registries. This promotes transparency and enhances risk management.

info

The response for the Enhanced Company Profile from the KYB Check service may take up to 30 minutes to be fully processed.

Request

"Requests" refer to the various HTTP methods used for interacting with the API, providing details on endpoint URLs, parameters, headers, request bodies, and examples.

Listing the Available Countries

Description:
The "Listing Available Countries" API serves as a valuable resource for users to explore and understand the geographic coverage of the product. By providing a comprehensive list of covered countries and associated details, users can gain a clear picture of the product's global availability and make informed decisions regarding its usage in various regions.

Method Call:   GET

API:

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

Http

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

Javascript

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/api/countries/read", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.thekyb.com/api/countries/read',
  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;

Python

import requests
import json

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

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)

Node

var axios = require("axios");

var config = {
  method: "get",
  url: "https://api.thekyb.com/api/countries/read",
  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

curl --location --request GET 'https://api.thekyb.com/api/countries/read' \
--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 "search" (company name) and/or "registration_number" as search parameters. You must provide at least one of search or registration_number. Both can be provided simultaneously. 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/api/search

Parameter	Description
search	Type: String Required: Yes (if registration_number not given) Minimum: 3 character Maximum: 128 characters. Description: Search parameter contains the name of the company that is being searched.This parameter requires a company name.
registration_number	Type: String Required: Yes (if search not given) Description: This parameter contains the registration number of the company that is being searched.
country_names	Type: Array Required: Yes Description: The parameter to search for companies in a specific country. Just input the country name, like ['united_kingdom'] for the United Kingdom or ['united_states.ohio'] for a specific state like Ohio. This way, you can easily customize your search for a particular country or explore all options.
search_type	Type: String Required: Optional Default: contains Between: contains, start_with or fuzzy "The search_type offers three distinct modes: 'start with,' 'contains,' and 'fuzzy.' start_with: option in the search functionality, the API will return a list of companies whose names begin with the characters provided by the user. For instance, if the user inputs "Apple," the API will display all companies whose names start with "Apple". contains: option, the search will encompass companies that have the provided keywords anywhere within their names. This means the API will return companies that contain the specified keywords in any part of their name, not just at the beginning. fuzzy: option allows for searching exact word matches with the company's name in any order.
services	Type: Array Required: Yes Description: This parameter defines the services provided by The KYB. To perform a KYB Check, ensure that the ["kyb_check"] service is included in the services parameter.
ttl	Type: Integer Required: Optional 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.

Http

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

{
    "search": "Testing company",
    "country_names": ["united_kingdom"],
    "search_type": "start_with",
    "services": ["kyb_check"]
}

Javascript

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({
  search: "Testing company",
  country_names: ["united_kingdom"],
  search_type: "start_with",
  services: ["kyb_check"],
});

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

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

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.thekyb.com/api/search',
  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 =>'{
    "search": "Testing company",
    "country_names": ["united_kingdom"],
    "search_type": "start_with",
    "services": ["kyb_check"]
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Accept: application/json',
    'token: YOUR_SECRET_KEY'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Python

import requests
import json

url = "https://api.thekyb.com/api/search"

payload = json.dumps({
  "search": "Testing company",
  "country_names": [
    "united_kingdom"
  ],
  "search_type": "start_with",
  "services": [
    "kyb_check"
  ]
})
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'token': 'YOUR_SECRET_KEY'
}

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

print(response.text)

Node

var axios = require("axios");
var data = JSON.stringify({
  search: "Testing company",
  country_names: ["united_kingdom"],
  search_type: "start_with",
  services: ["kyb_check"],
});

var config = {
  method: "post",
  url: "https://api.thekyb.com/api/search",
  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

curl --location --request POST 'https://api.thekyb.com/api/search' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'token: YOUR_SECRET_KEY' \
--data-raw '{
    "search": "Testing company",
    "country_names": ["united_kingdom"],
    "search_type": "start_with",
    "services": ["kyb_check"]
}'

Retrieving Companies’ Profiles

Description:
When users perform a search using the API, the system will retrieve a list of companies from the official registries that match the provided search criteria. For instance, if a user searches for the company name "Apple" within the United States, the API will display all the companies registered in the United States that match the search term "Apple". This API breaks down the data into smaller, manageable pieces called "pages". Each page contains a limited number of results, which is determined by the "limit" value. By specifying the "page" number and "limit" value in the request, users can access different segments of the data retrieved by the request ID. This approach is helpful for handling large datasets more efficiently, as it allows users to retrieve data in smaller chunks, one page at a time, rather than getting the entire dataset all at once.

Method Call:   GET

API:

https://api.thekyb.com/api/readKybResponse?request_id=REQUEST_ID&page=PAGE&limit=LIMIT

Parameter	Description
request_id	Type: String Required: Yes Description: This is the unique request ID of request and can be generated by performing a "search" request.
page	Type: String Required: Optional 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: Optional 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.

Http

GET /api/readKybResponse?request_id=REQUEST_ID&page=PAGE&limit=LIMIT HTTP/1.1
Host: api.thekyb.com
Content-Type: application/json
Accept: application/json
token: YOUR_SECRET_KEY

Javascript

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/api/readKybResponse?request_id=REQUEST_ID&page=PAGE&limit=LIMIT",
  requestOptions,
)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.thekyb.com/api/readKybResponse?request_id=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;

Python

import requests
import json

url = "https://api.thekyb.com/api/readKybResponse?request_id=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)

Node

var axios = require("axios");

var config = {
  method: "get",
  url: "https://api.thekyb.com/api/readKybResponse?request_id=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

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

Enhanced Company Profile

Description:
This API provides users the ability to select their desired company from the list of companies displayed on a page after search is performed. Each listed company profile includes registration details and a unique "company_id". This "company_id" serves as a special code to uniquely identify each company in the dataset.
To access detailed information about a specific company, users can extract the "company_id" from the results. With this "company_id" in hand, users can then use it along with the original "request_id" (which initiated the data retrieval process) to retrieve the comprehensive profile of the chosen company.

Method Call:   GET

API:

https://api.thekyb.com/api/companies/read?company_id=COMPANY_ID&request_id=REQUEST_ID

Parameter	Description
company_id	Required: Yes Type: String Description: The "company_id" acts like a special code or label assigned to each company, allowing easy and precise access to detailed information about that particular company. It serves as a key to unlock the specific profile or data associated with the company within the API's stored records.
request_id	Required: Yes Type: String Description: This is the unique Request ID of request and can be generated by performing a "search" request.

Http

GET /api/companies/read?company_id=COMPANY_ID&request_id=REQUEST_ID HTTP/1.1
Host: api.thekyb.com
Content-Type: application/json
Accept: application/json
token: YOUR_SECRET_KEY

Javascript

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/api/companies/read?company_id=COMPANY_ID&request_id=REQUEST_ID",
  requestOptions,
)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.thekyb.com/api/companies/read?company_id=COMPANY_ID&request_id=REQUEST_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;

Python

import requests
import json

url = "https://api.thekyb.com/api/companies/read?company_id=COMPANY_ID&request_id=REQUEST_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)

Node

var axios = require("axios");

var config = {
  method: "get",
  url: "https://api.thekyb.com/api/companies/read?company_id=COMPANY_ID&request_id=REQUEST_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

curl --location --request GET 'https://api.thekyb.com/api/companies/read?company_id=COMPANY_ID&request_id=REQUEST_ID' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'token: YOUR_SECRET_KEY'

AML For Company

Description:
This API enables users to submit an AML request for a company. With our AML verification service, businesses can proactively safeguard themselves against the threats posed by money laundering and illegal activities.

Method Call:   POST

API:

https://api.thekyb.com/api/performCompanyAml

Parameter	Description
company_id	Required: Yes Type: String Description: The "company_id" parameter is the unique code for the company you're checking for Anti-Money Laundering (AML) activity.
request_id	Required: Yes Type: String Description: The "request_id" parameter is a string identifier that must be included in the request. This ID uniquely identifies the specific AML verification request being made.

Http

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

{
    "company_id": "COMPANY_ID",
    "request_id": "REQUEST_ID"
}

Javascript

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

var requestPayload = JSON.stringify({
  company_id: "COMPANY_ID",
  request_id: "REQUEST_ID",
});

var requestOptions = {
  method: "POST",
  headers: requestHeaders,
  body: requestPayload,
  redirect: "follow",
};

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

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.thekyb.com/api/performCompanyAml',
  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 =>'{
    "company_id": "COMPANY_ID",
    "request_id": "REQUEST_ID"
}',
  CURLOPT_HTTPHEADER => array(
    'Accept: application/json',
    'Content-Type: application/json',
    'token: YOUR_SECRET_KEY'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Python

import requests
import json

url = "https://api.thekyb.com/api/performCompanyAml"

payload = json.dumps({
  "company_id": "COMPANY_ID",
  "request_id": "REQUEST_ID"
})
headers = {
  'Accept': 'application/json',
  'Content-Type': 'application/json',
  'token': 'YOUR_SECRET_KEY'
}

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

print(response.text)

Node

var axios = require("axios");
var data = JSON.stringify({
  company_id: "COMPANY_ID",
  request_id: "REQUEST_ID",
});

var config = {
  method: "post",
  url: "https://api.thekyb.com/api/performCompanyAml",
  headers: {
    Accept: "application/json",
    "Content-Type": "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

curl --location --request POST 'https://api.thekyb.com/api/performCompanyAml' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'token: YOUR_SECRET_KEY' \
--data-raw '{
    "company_id": "COMPANY_ID",
    "request_id": "REQUEST_ID"
}'

AML For Person

Description:
This API enables users to seamlessly submit AML requests for individuals, leveraging our robust verification service to efficiently screen against sanction lists and regulatory databases, ensuring compliance with ease.

info

Our AML service checks individuals, including company person or all company officers.

Method Call:   POST

API:

https://api.thekyb.com/api/performOfficersAml

Parameter	Description
company_id	Required: Yes Type: String Description: The "company_id" parameter is the unique code for the company you're checking for Anti-Money Laundering (AML) activity.
request_id	Required: Yes Type: String Description: The "request_id" parameter is a string identifier that must be included in the request. This ID uniquely identifies the specific AML verification request being made.
person_name	Required: Optional Type: String Description: The "person_name" parameter is a string identifier that must be included in the request. This parameter identifies the specific AML verification request being made. It is required when creating an AML service request for a specific person.person.

Http

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

{
    "company_id": "COMPANY_ID",
    "request_id": "REQUEST_ID",
    "person_name":"PERSON_NAME"
}

Javascript

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

var requestPayload = JSON.stringify({
  company_id: "COMPANY_ID",
  request_id: "REQUEST_ID",
  person_name: "PERSON_NAME",
});

var requestOptions = {
  method: "POST",
  headers: requestHeaders,
  body: requestPayload,
  redirect: "follow",
};

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

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.thekyb.com/api/performOfficersAml',
  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 =>'{
    "company_id": "COMPANY_ID",
    "request_id": "REQUEST_ID",
    "person_name":"PERSON_NAME"
}',
  CURLOPT_HTTPHEADER => array(
    'Accept: application/json',
    'Content-Type: application/json',
    'token: YOUR_SECRET_KEY'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Python

import requests
import json

url = "https://api.thekyb.com/api/performOfficersAml"

payload = json.dumps({
  "company_id": "COMPANY_ID",
  "request_id": "REQUEST_ID",
  "person_name":"PERSON_NAME"
})
headers = {
  'Accept': 'application/json',
  'Content-Type': 'application/json',
  'token': 'YOUR_SECRET_KEY'
}

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

print(response.text)

Node

var axios = require("axios");
var data = JSON.stringify({
  company_id: "COMPANY_ID",
  request_id: "REQUEST_ID",
  person_name: "PERSON_NAME",
});

var config = {
  method: "post",
  url: "https://api.thekyb.com/api/performOfficersAml",
  headers: {
    Accept: "application/json",
    "Content-Type": "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

curl --location --request POST 'https://api.thekyb.com/api/performOfficersAml' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'token: YOUR_SECRET_KEY' \
--data-raw '{
    "company_id": "COMPANY_ID",
    "request_id": "REQUEST_ID",
    "person_name":"PERSON_NAME"
}'

Response

The KYB Verification API offers two types of responses when a verification request is made: an HTTP response and a callback response. Both responses are presented in JSON format with an application/json header. The response header also includes a Key Signature, which is utilized for verifying the authenticity of the response source.

Listing the Available Countries

Description:
The "Listing Available Countries" response serves as a valuable resource for users to explore and understand the geographic coverage of the product. By providing a comprehensive list of covered countries and associated details, users can gain a clear picture of the product's global availability and make informed decisions regarding its usage in various regions.

API:

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

Response:

{
  "error": false,
  "message": "countries fetched successfully",
  "data": {
    "countries": [
      {
        "country_name": "united_kingdom",
        "states": [],
        "country_code": "gb",
        "flag_url": "https://api.thekyb.com/uploads/countries/gb.png"
      },
      {
        "country_name": "united_states",
        "states": [
          "alabama",
          "alaska",
          "arizona",
          "arkansas",
          "california",
          ...
        ],
        "country_code": "us",
        "flag_url": "https://api.thekyb.com/uploads/countries/us.png"
      },
      ...
    ]
  }
}

Response Parameters:

Parameter	Description
error	The "error" parameter can have a value of either "true" or "false." In the current scenario, since there were no errors during the request processing, the value of "error" is "false." However, in situations where errors occur, such as missing required parameters or criteria not being met, the value of the "error" parameter will change to "true."
message	The "message" field in API response formats provides a descriptive text or notification intended to convey additional information or instructions to the API consumer. It is commonly used to communicate relevant details about the response, such as success messages, error messages, or any other informative content that aids in understanding the outcome of the API request. The "message" field helps provide context and guidance to the API consumer regarding the status or result of the API operation.
data	The "data" field in API documentation refers to the main payload or content of the API response. It contains the actual information, results, or entities being transmitted back to the API consumer. The structure and format of the "data" field depend on the specific API and the nature of the response.
data.countries	The "data.countries" key within the API response provides users with a comprehensive list of countries covered in the search results. It facilitates a clear understanding of the geographic scope of the retrieved companies.
data.*.country_name	The "data.*.country_name" key in the API response provides users with countries’ name from which the companies were sourced. This valuable information aids users in analyzing the geographical scope of the search results.
data.*.states	The "data.*.states" key in the API response provides users with details about the states or regions associated with the companies retrieved from specific countries.
data.*.country_code	The two-letter country code associated with the country (for example, "gb", "us").
data.*.flag_url	URL of the country flag image returned by the API (for example, "https://api.thekyb.com/uploads/countries/gb.png").

Company Search

Description:
Whenever a user performs the company search request from official business registries a unique id called "request_id" will be generated and the request_id will be shown in the response.

API:

https://api.thekyb.com/api/search

Response:

{
    "request_id": "REQUEST_ID",
    "service_id": "SERVICE_ID"
}

Response Parameters:

Parameter	Description
request_id	This is the unique request ID of request and can be generated by performing a "search" request.
service_id	This is the unique service ID of service and can be generated by performing a "search" request.

Error Response:

{
  "error": true,
  "message": "Invalid country names: United_kingdom",
  "data": {}
}

Error Response Parameters:

Parameter	Description
error	true when the request fails (for example, invalid country names or missing required parameters).
message	Human-readable error description (for example, "Invalid country names: United_kingdom").
data	Response payload; typically an empty object {} on failure.

Retrieving Companies’ Profiles

Description:
When users perform a search using the request API then in the response, the system will retrieve a list of companies from the official registries that match the provided search criteria so users can view the companies’ profiles.
For example, if a user searches for the company name "Apple" within the United States, the API will display all the companies registered in the United States that match the search term "Apple".

API:

https://api.thekyb.com/api/readKybResponse?request_id=REQUEST_ID&page=PAGE&limit=LIMIT

Response:

Company Profile Response Data

{
    "error": false,
    "message": "request data fetched successfully",
    "data": {
        "kyb_request": {
            "country_codes": [],
            "registration_number": null,
            "request_random_id": "REQUEST_RANDOM_ID",
            "service_id": "SERVICE_ID",
            "search_type": "contains",
            "status": "resolved",
            "services": [
                "kyb_check"
            ],
            "extensive_data": [],
            "search_text": "COMPANY_NAME",
            "_id": "REQUEST_ID"
        },
        "services_in_progress": [],
        "services_completed": [],
        "resolved_percentage": 100,
        "fetched_countries_with_states": [
            {
                "country_name": "united_kingdom",
                "states": []
            }
        ],
        "fetched_countries": [
            "united_kingdom"
        ],
        "secondary_source": true,
        "request_status": "resolved",
        "kyb_request_data": [
            {
                "name": "COMPANY_NAME",
                "registration_number": "REGISTRATION_NUMBER",
                "registration_date": "YYYY-MM-DD",
                "type": "COMPANY_TYPE",
                "status": "active",
                "risk_level": "low risk",
                "verification_status": "verified",
                "extensive_data": [
                    "Officers",
                    "Financial Performance",
                    "Filing History",
                    "Branches",
                    "Change History",
                    "Announcements",
                    "Additional Information",
                    "Documents"
                ],
                "id": "COMPANY_ID",
                "request_id": "REQUEST_ID"
            }
        ],
        "pagination": {
            "total": 1,
            "per_page": 10,
            "current_page": 1,
            "last_page": 1,
            "from": 1,
            "to": 1
        }
    }
}

Response Parameters:

Parameter	Description
error	The "error" parameter can have a value of either "true" or "false." In the current scenario, since there were no errors during the request processing, the value of "error" is "false." However, in situations where errors occur, such as missing required parameters or criteria not being met, the value of the "error" parameter will change to "true".
message	The "message" field in API response formats provides a descriptive text or notification intended to convey additional information or instructions to the API consumer. It is commonly used to communicate relevant details about the response, such as success messages, error messages, or any other informative content that aids in understanding the outcome of the API request. The "message" field helps provide context and guidance to the API consumer regarding the status or result of the API operation.
data	The "data" field in API documentation refers to the main payload or content of the API response. It contains the actual information, results, or entities being transmitted back to the API consumer. The structure and format of the "data" field depend on the specific API and the nature of the response.
data.kyb_request	Contains the details of the KYB request, including search parameters, status, services, and related request information.
data.kyb_request.country_codes	Array of country codes associated with the KYB request.
data.kyb_request.status	Status of the KYB request (for example, "resolved").
data.kyb_request.extensive_data	Array of extensive-data options associated with the KYB request.
data.services_in_progress	Array of services that are still in progress for this request.
data.services_completed	Array of services that have completed for this request.
data.resolved_percentage	The "resolved_percentage" parameter in this API represents the percentage of completion for the search process within the selected countries. For example, if a user chooses to search for data in 5 countries, and the API successfully retrieves results from 4 out of those 5 countries, the "resolved_percentage" will be calculated as 80%. This parameter provides valuable feedback to users, indicating the progress and completeness of the search across the specified countries, enabling efficient tracking and analysis of search results.
data.fetched_countries_with_states	The "fetched_countries_with_states" parameter offers information on the states within the selected country, if applicable. The API's results are determined by the company registration address, specifically focusing on companies officially registered within the available states of the chosen country. This feature ensures that the retrieved data aligns with the specified states, providing accurate and relevant company information for users.
data.fetched_countries	The "fetched_countries" key includes the names of all countries where the company is officially registered.
data.secondary_source	This parameter shows that certain company profiles originate from a secondary data source.
data.request_status	The current status of the KYB Check request. "request_status": "pending" indicates that the request is still in progress and has not yet been completed. "request_status": "resolved" indicates completion of service request.
data.kyb_request_data	The key "kyb_request_data" shows the companies matching the search criteria, including name, registration number, registration date, type, status, risk level, verification status, extensive_data, company id, and request_id. Fields with no value for a company (for example, registration_date) are left out of that company's object.
data.pagination	data.pagination is used to control and navigate through large result sets when retrieving paginated data.
data.pagination.total	"pagination.total" refers to the total number of results or items available in a paginated API response. This value indicates the overall count of items that match the search criteria or data retrieval request.
data.pagination.per_page	"data.pagination.per_page" refers to the number of data items or results displayed per page during pagination. This value indicates how many data entries or companies’ profiles are presented to the user in a single page of the API response.
data.pagination.current_page	"data.pagination.current_page" represents the page number of the current set of data being displayed. This value indicates which specific page of the API response the user is currently viewing. As the user navigates through the paginated results, the "current_page" parameter helps keep track of their progress within the dataset, enabling efficient access to different segments of the data.
data.pagination.last_page	In the API response, "data.pagination.last_page" indicates the page number of the last page available in the paginated results. This value helps users understand the total number of pages in the response and facilitates easy navigation through the complete dataset. When users reach the last page, they know they have accessed all the available data items within the paginated response.
data.pagination.from	"data.pagination.from" shows the position of the first data item on the current page of the API response. It helps users know where the displayed data starts within the complete dataset. For example in the above response the value of pagination.from is 1.
data.pagination.to	In the API response, "data.pagination.to" represents the position of the last data item displayed on the current page. It helps users understand where the displayed data ends within the complete dataset, making it easier to keep track of the data range being shown on the current page of the paginated results.

Enhanced Company Profile

Description:
This response provides users the ability to view their desired company’s detailed profile from the list of companies displayed on a page after search is performed. Each listed company profile includes registration details and a unique "company_id." This "company_id" serves as a special code to uniquely identify each company in the dataset.
To access detailed information about a specific company, users can extract the "company_id" from the results. With this "company_id" in hand, users can then use it along with the original "request_id" (which initiated the data retrieval process) to receive the comprehensive profile of the selected company in response.

API:

https://api.thekyb.com/api/companies/read?company_id=COMPANY_ID&request_id=REQUEST_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".

info

Some fields are conditional. company_aml_request_id, company_aml_ongoing_monitoring, company_aml_request_status, and company_aml_status are returned only when the aml_for_company service has been executed for the requested entity. accounts_detail and confirmation_statement_detail populate only when relevant registry data is present.

Response (without AML):

Enhanced Company Response Data (without AML)

{
  "error": false,
  "message": "company data fetched successfully",
  "data": {
    "name": "COMPANY_NAME",
    "registration_number": "REGISTRATION_NUMBER",
    "registration_date": "",
    "status": "active",
    "type": "COMPANY_TYPE",
    "description": "",
    "incorporation_date": null,
    "industries": null,
    "tax_number": null,
    "dissolution_date": null,
    "inactive_date": null,
    "meta_detail": {},
    "contacts_detail": [
      {
        "type": "website_link",
        "value": "https://example.com",
        "enriched": false,
        "is_primary_link": false,
        "source": "",
        "meta_detail": []
      }
    ],
    "previous_names_detail": [
      {
        "company_name": "PREVIOUS_COMPANY_NAME",
        "update_date": "YYYY-MM-DD",
        "meta_detail": {},
        "source": ""
      }
    ],
    "addresses_detail": [
      {
        "address": "COMPANY_ADDRESS",
        "type": "Principal Place of Business",
        "meta_detail": {},
        "source": ""
      }
    ],
    "announcements_detail": [],
    "people_detail": [],
    "additional_detail": [
      {
        "type": "Current Names Detail",
        "data": [
          {
            "name": "COMPANY_NAME",
            "update_date": "YYYY-MM-DD",
            "name_used_as": "Registered"
          }
        ],
        "source": ""
      }
    ],
    "parent_companies": [],
    "branches": [],
    "beneficial_owners_detail": [],
    "company_extra_detail": {},
    "identifiers": [],
    "capital_stock_information": [],
    "industries_detail": [],
    "ownership_structure": {},
    "financial_detail": {},
    "risk_level": "low risk",
    "verification_status": "verified",
    "registries_detail": [
      {
        "name": "REGISTRY_NAME",
        "source_type": "official"
      }
    ],
    "last_updated_at": null,
    "people_network_detail": {},
    "request_status": "resolved",
    "primary_source": false,
    "company_fetched_data_status": "resolved",
    "favorite": "false",
    "secondary_source": false,
    "company_registration_period": "",
    "company_incorporation_period": "",
    "years_since_dissolution": "",
    "similar_companies": [
      {
        "_id": "COMPANY_ID",
        "name": "SIMILAR_COMPANY_NAME",
        "country_name": "united_kingdom",
        "request_id": "REQUEST_ID",
        "country_flag": "https://api.thekyb.com/uploads/countries/gb.png"
      }
    ],
    "people_designation_detail": [],
    "people_nationality_detail": [],
    "filings_detail": [],
    "key_figure_table": [],
    "overview_financial_close_table": [],
    "company_industries_keywords": [],
    "solidity": {},
    "profit_margin": {},
    "cash_flow": {},
    "financial_statement_period_table": [],
    "income_statement_table": [],
    "wages_table": [],
    "balance_sheet_table": [],
    "country_name": "united_kingdom",
    "country_flag": "https://api.thekyb.com/uploads/countries/gb.png",
    "jurisdiction_code": "GB",
    "key_figures_meters_graphs": [],
    "organization_structure": [],
    "people_detail_graph": [],
    "affiliated_companies": [],
    "working_on_files": false,
    "services_in_progress": [],
    "services_completed": [],
    "ownership_shares_detail": [],
    "voting_shares_detail": [],
    "request_id": "REQUEST_ID",
    "_id": "COMPANY_ID"
  }
}

Response (with AML):

note

The following sample includes AML fields. These keys are returned only when the aml_for_company service has been executed for the requested entity.

Enhanced Company Response Data (with AML)

{
  "error": false,
  "message": "company data fetched successfully",
  "data": {
    "name": "COMPANY_NAME",
    "registration_number": "REGISTRATION_NUMBER",
    "registration_date": "",
    "status": "active",
    "type": "COMPANY_TYPE",
    "description": "",
    "incorporation_date": null,
    "industries": null,
    "tax_number": null,
    "dissolution_date": null,
    "inactive_date": null,
    "meta_detail": {},
    "contacts_detail": [
      {
        "type": "website_link",
        "value": "https://example.com",
        "enriched": false,
        "is_primary_link": false,
        "source": "",
        "meta_detail": []
      }
    ],
    "previous_names_detail": [
      {
        "company_name": "PREVIOUS_COMPANY_NAME",
        "update_date": "YYYY-MM-DD",
        "meta_detail": {},
        "source": ""
      }
    ],
    "addresses_detail": [
      {
        "address": "COMPANY_ADDRESS",
        "type": "Principal Place of Business",
        "meta_detail": {},
        "source": ""
      }
    ],
    "announcements_detail": [],
    "people_detail": [],
    "additional_detail": [
      {
        "type": "Current Names Detail",
        "data": [
          {
            "name": "COMPANY_NAME",
            "update_date": "YYYY-MM-DD",
            "name_used_as": "Registered"
          }
        ],
        "source": ""
      }
    ],
    "parent_companies": [],
    "branches": [],
    "beneficial_owners_detail": [],
    "company_extra_detail": {},
    "identifiers": [],
    "capital_stock_information": [],
    "industries_detail": [],
    "ownership_structure": {},
    "financial_detail": {},
    "risk_level": "low risk",
    "verification_status": "verified",
    "registries_detail": [
      {
        "name": "REGISTRY_NAME",
        "source_type": "official"
      }
    ],
    "last_updated_at": null,
    "people_network_detail": {},
    "request_status": "resolved",
    "primary_source": false,
    "company_fetched_data_status": "resolved",
    "favorite": "false",
    "secondary_source": false,
    "company_registration_period": "",
    "company_incorporation_period": "",
    "years_since_dissolution": "",
    "similar_companies": [
      {
        "_id": "COMPANY_ID",
        "name": "SIMILAR_COMPANY_NAME",
        "country_name": "united_kingdom",
        "request_id": "REQUEST_ID",
        "country_flag": "https://api.thekyb.com/uploads/countries/gb.png"
      }
    ],
    "people_designation_detail": [],
    "people_nationality_detail": [],
    "filings_detail": [],
    "key_figure_table": [],
    "overview_financial_close_table": [],
    "company_industries_keywords": [],
    "solidity": {},
    "profit_margin": {},
    "cash_flow": {},
    "financial_statement_period_table": [],
    "income_statement_table": [],
    "wages_table": [],
    "balance_sheet_table": [],
    "country_name": "united_kingdom",
    "country_flag": "https://api.thekyb.com/uploads/countries/gb.png",
    "jurisdiction_code": "GB",
    "key_figures_meters_graphs": [],
    "organization_structure": [],
    "people_detail_graph": [],
    "affiliated_companies": [],
    "working_on_files": false,
    "services_in_progress": [],
    "services_completed": [],
    "ownership_shares_detail": [],
    "voting_shares_detail": [],
    "request_id": "REQUEST_ID",
    "_id": "COMPANY_ID",
    "company_aml_request_id": "AML_REQUEST_ID",
    "company_aml_ongoing_monitoring": false,
    "company_aml_request_status": "resolved",
    "company_aml_status": "clear"
  }
}

Response Parameters:

Parameter	Description
error	true or false. false indicates the request completed without errors.
message	Descriptive status message for the API response.
data	Main company profile payload returned by the API.
data._id	Unique company identifier (COMPANY_ID).
data.request_id	Unique request identifier associated with the company profile.
data.name	Registered company name.
data.registration_number	Company registration number.
data.registration_date	Company registration date, when available.
data.status	Current company status (for example, "active").
data.type	Company type or legal form.
data.country_name	Country where the company is registered.
data.country_flag	URL of the country flag image.
data.jurisdiction_code	Jurisdiction code (for example, "GB").
data.description	Company description, when available.
data.incorporation_date	Incorporation date, when available.
data.industries	Industry information, when available.
data.tax_number	Tax number, when available.
data.dissolution_date	Dissolution date, when available.
data.inactive_date	Inactive date, when available.
data.favorite	Indicates whether the company is marked as favorite.
data.meta_detail	Additional registry-specific details about the company. The keys depend on the country's registry, so they differ between companies (for example contract_date, activity and update_date for Argentina). It is {} when the registry provides no extra details.
data.contacts_detail	Contact details such as website or phone number. Each item has type, value, enriched (boolean), is_primary_link (boolean), source ("primary", "secondary" or "") and meta_detail.
data.contacts_detail[].enriched	Indicates whether the contact value has been enriched.
data.contacts_detail[].is_primary_link	Indicates whether the contact is the primary link.
data.contacts_detail[].source	Source of the contact information.
data.previous_names_detail	Previous company names. Each item has company_name, update_date and meta_detail, plus status and source when available. Empty keys are left out.
data.previous_names_detail[].source	Source of the previous name record.
data.addresses_detail	Company address records. Each item has address and type, plus description, meta_detail and source when available. Empty keys are left out.
data.addresses_detail[].source	Source of the address record.
data.announcements_detail	Company announcements, when available.
data.people_detail	People associated with the company.
data.additional_detail	Additional structured company details. Each item has type, data and, when available, source. The keys inside data[] depend on type. For example, "Current Names Detail" entries have name, update_date and name_used_as.
data.additional_detail[].source	Source of the additional detail record.
data.parent_companies	Parent company records, when available. Keys depend on the registry, for example name, company_number, country_name and country_flag. meta_detail and source appear when available. Empty keys are left out.
data.branches	Branch records, when available. Same item format as parent_companies. meta_detail and source appear only when they have a value.
data.beneficial_owners_detail	Beneficial owner records, when available.
data.company_extra_detail	Extra company detail object.
data.identifiers	Company identifiers, when available.
data.capital_stock_information	Capital stock information, when available.
data.industries_detail	Detailed industry records, when available.
data.ownership_structure	Ownership structure object.
data.financial_detail	Financial detail object.
data.risk_level	Risk level assigned to the company.
data.verification_status	Verification status of the company profile.
data.registries_detail	Registry sources for the company.
data.last_updated_at	Timestamp of the last update, when available.
data.people_network_detail	People network detail object.
data.people_detail_graph	People detail graph data.
data.organization_structure	Organization structure data.
data.affiliated_companies	Affiliated company records.
data.similar_companies	Similar company records. Each item has _id, name, country_name, request_id and country_flag.
data.similar_companies[]._id	Unique identifier of the similar company.
data.similar_companies[].request_id	Request ID associated with the similar company.
data.similar_companies[].country_flag	Country flag URL for the similar company.
data.people_designation_detail	People designation detail records.
data.people_nationality_detail	People nationality detail records.
data.filings_detail	Filing records, when available.
data.key_figure_table	Key figure table data.
data.key_figures_meters_graphs	Key figures meters and graphs data.
data.overview_financial_close_table	Overview financial close table data.
data.financial_statement_period_table	Financial statement period table data.
data.income_statement_table	Income statement table data.
data.balance_sheet_table	Balance sheet table data.
data.wages_table	Wages table data.
data.company_industries_keywords	Industry keywords associated with the company.
data.solidity	Solidity metrics object.
data.profit_margin	Profit margin metrics object.
data.cash_flow	Cash flow metrics object.
data.request_status	Status of the company profile request.
data.primary_source	Indicates whether the profile is from a primary source.
data.secondary_source	Indicates whether the profile is from a secondary source.
data.company_fetched_data_status	Fetch status of the company data.
data.company_registration_period	How long ago the company was registered, for example "more than 3 years". It is an empty string when registration_date is not available.
data.company_incorporation_period	How long ago the company was incorporated. It is an empty string when incorporation_date is not available.
data.years_since_dissolution	How long ago the company was dissolved. It is an empty string when dissolution_date is not available.
data.ownership_shares_detail	Ownership shares detail records.
data.voting_shares_detail	Voting shares detail records.
data.working_on_files	Indicates whether file processing is in progress.
data.services_in_progress	Services currently in progress.
data.services_completed	Services that have completed.
data.company_aml_request_id	Optional / Conditional. AML request ID. Returned only when the aml_for_company service has been executed for the requested entity.
data.company_aml_ongoing_monitoring	Optional / Conditional. Type: Boolean. Whether ongoing AML monitoring is turned on for the company. Returned only when the aml_for_company service has been executed for the requested entity.
data.company_aml_request_status	Optional / Conditional. AML request status. Returned only when the aml_for_company service has been executed for the requested entity.
data.company_aml_status	Optional / Conditional. AML status for the company. Returned only when the aml_for_company service has been executed for the requested entity and company_aml_request_status is "resolved".
data.accounts_detail	Optional / Conditional. Accounts detail object with last_account, next_account and due_by_date. Returned only when the registry provides accounts data; otherwise the key is left out.
data.confirmation_statement_detail	Optional / Conditional. Confirmation statement detail object with last_account, next_account and due_by_date. Returned only when the registry provides confirmation statement data; otherwise the key is left out.

AML For Company

Description:
The "AML for company" request response will provide the detailed information of the aml for company. Once your request results are ready for delivery, we will notify you.

Here are the keys "company_aml_request_id", "company_aml_request_status", and "company_aml_status" provided in detail "Enhanced Company Response". You can use them to check the AML results for the company.

info

After completing the service, you can access the status of your request at the specified endpoint. Here is "Enhanced Company Response" for your request.

API:

https://api.thekyb.com/api/performCompanyAml

Response:

{
  "error": false,
  "message": "Kyb Company Aml Started",
  "data": {
      "aml_request_id": "AML_REQUEST_ID"
   }
}

Response Parameters:

Parameter	Description
error	The "error" parameter can have a value of either "true" or "false." In the current scenario, since there were no errors during the request processing, the value of "error" is "false." However, in situations where errors occur, such as missing required parameters or criteria not being met, the value of the "error" parameter will change to "true."
message	The "message" field in API response formats provides a descriptive text or notification intended to convey additional information or instructions to the API consumer. It is commonly used to communicate relevant details about the response, such as success messages, error messages, or any other informative content that aids in understanding the outcome of the API request. The "message" field helps provide context and guidance to the API consumer regarding the status or result of the API operation.
data	The "data" field in API documentation refers to the main payload or content of the API response. It contains the actual information, results, or entities being transmitted back to the API consumer. The structure and format of the "data" field depend on the specific API and the nature of the response.
data.aml_request_id	The "data.aml_request_id" key within the API response provides the unique request id for your request.

AML For Person

Description:
The "AML for person" request queues an AML screening for every eligible company officer and beneficial owner (or only for person_name, if you send it). The response comes back immediately and contains the queued requests in the "aml_for_people_requests" array. Each request starts with status: "pending". The screening itself runs in the background, and we will notify you when the results are ready.

A person is skipped if they already have a pending AML request, or a resolved one with a match_status of "potential match" or "no match", for this company. If your account has a limited number of AML requests left, only that many people are queued.

Use the _id of each item to match it with the "aml_request_id" key in the "people_detail" and "beneficial_owners_detail" objects of the "Enhanced Company Response". Those objects also carry "aml_request_status" and "aml_status" once the screening is complete. All requests from one call share the same batch_id.

info

The AML results are not part of this response. After the service completes, you can get them at the endpoint below. Here is "Enhanced Company Response" for your request.

API:

https://api.thekyb.com/api/performOfficersAml

Response:

{
  "error": false,
  "message": "Performing Aml on Officers",
  "data": {
    "aml_for_people_requests": [
      {
        "user_id": "USER_ID",
        "search_name": "john doe",
        "aml_modified_name": "john doe",
        "company_id": "COMPANY_ID",
        "service_id": "SERVICE_ID",
        "kyb_response_id": "KYB_RESPONSE_ID",
        "fuzziness": "90",
        "entity_type": ["Person", "Company", "Organization"],
        "categories": [
          "PEP Level 1",
          "PEP Level 2",
          "PEP Level 3",
          "PEP Level 4",
          "Fitness and Probity",
          "SIP",
          "Warnings and Regulatory Enforcement",
          "Sanctions",
          "SIE",
          "Insolvency"
        ],
        "country_names": [],
        "country_codes": [],
        "unique_identifier": "",
        "birth_incorporation_date": "",
        "services": ["kyb_check", "aml_for_people"],
        "exact_search": false,
        "rca_search": false,
        "alias_search": false,
        "ongoing_monitoring": false,
        "request_type": "for_people",
        "batch_id": "BATCH_ID",
        "status": "pending",
        "updated_at": "2026-01-01T00:00:00.000000Z",
        "created_at": "2026-01-01T00:00:00.000000Z",
        "_id": "AML_REQUEST_ID",
        "for_single_person": true
      }
    ]
  }
}

Response Parameters:

Parameter	Description
error	false when the AML requests were queued. true when the request failed, for example when required parameters are missing or no eligible people were found.
message	A short description of the result. On success it is "Performing Aml on Officers".
data	The response payload.
data.aml_for_people_requests	An array with one object for each person queued for AML screening.
data.aml_for_people_requests[]._id	The unique ID of the AML request. It matches aml_request_id in the person's entry in the "Enhanced Company Response".
data.aml_for_people_requests[].batch_id	An ID shared by all AML requests created in the same call.
data.aml_for_people_requests[].status	The processing status of the request. It is always "pending" in this response.
data.aml_for_people_requests[].search_name	The name being screened, in lowercase.
data.aml_for_people_requests[].aml_modified_name	The name sent for screening, with prefixes (such as titles) removed.
data.aml_for_people_requests[].request_type	The type of AML request. It is always "for_people" for this endpoint.
data.aml_for_people_requests[].kyb_response_id	The ID of the company (company_id) the person belongs to.
data.aml_for_people_requests[].service_id	The ID of the KYB service used for the request.
data.aml_for_people_requests[].user_id	The ID of the user who made the request.
data.aml_for_people_requests[].company_id	The ID of the account the user belongs to.
data.aml_for_people_requests[].services	The services enabled on the KYB service.
data.aml_for_people_requests[].entity_type	The entity types screened against. These come from your AML preferences, or default to Person, Company and Organization.
data.aml_for_people_requests[].categories	The AML categories screened against. These come from your AML preferences, or the default categories.
data.aml_for_people_requests[].fuzziness	The fuzzy-match threshold for name matching. The default is "90".
data.aml_for_people_requests[].exact_search	Type: Boolean. Whether only exact name matches are returned.
data.aml_for_people_requests[].rca_search	Type: Boolean. Whether relatives and close associates (RCA) are searched.
data.aml_for_people_requests[].alias_search	Type: Boolean. Whether aliases are searched.
data.aml_for_people_requests[].ongoing_monitoring	Type: Boolean. Whether ongoing AML monitoring is turned on for this person.
data.aml_for_people_requests[].country_names	The country names used to narrow the screening, if any.
data.aml_for_people_requests[].country_codes	The country codes used to narrow the screening, if any.
data.aml_for_people_requests[].unique_identifier	A unique identifier for the person, if one was provided.
data.aml_for_people_requests[].birth_incorporation_date	The person's date of birth, if one was provided.
data.aml_for_people_requests[].created_at	When the AML request was created.
data.aml_for_people_requests[].updated_at	When the AML request was last updated.
data.aml_for_people_requests[].for_single_person	Optional / Conditional. Returned as true whenever the person_name parameter is included in the request, even if its value is empty. Not returned when person_name is left out.

Error Response (no eligible people):

This response comes back with HTTP status 422 when no people could be queued. This happens when the company has no officers or beneficial owners, when everyone has already been screened or is still pending, or when person_name matches nobody who can be screened.

{
  "error": true,
  "message": "No people were found to perform AML.",
  "data": {}
}