Paid Documents Extraction
Our "Paid Documents Extraction" service offers comprehensive access to official business documents from various global registries.
Users can explore our platform's geographic reach through a detailed "List of available countries", ensuring they understand the extent of our service coverage.
The "Document search feature" allows users to find specific documents related to a particular company or business entity within their selected country, providing direct access to data from official registries. Additionally, users have the option to "Purchase" these documents, ensuring seamless acquisition from the official registries of their chosen country.
Request
"Requests" refer to the various HTTP methods used for interacting with the API, providing details on endpoint URLs, parameters, headers, request bodies.
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/getDocumentCountries
- Http
- Javascript
- PHP
- Python
- Node
- cURL
GET /api/getDocumentCountries 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/api/getDocumentCountries", 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/api/getDocumentCountries',
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/api/getDocumentCountries"
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/api/getDocumentCountries",
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/api/getDocumentCountries' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'token: YOUR_SECRET_KEY'
Document Search
Description:
The functionality of "getCountryPaidDocuments" API allows users to search for documents. This API allows to search against particular country. It directly accesses and fetches data from the official registries of the selected country.
Method Call: POST
API:
https://api.thekyb.com/api/getCountryPaidDocuments
Parameter | Description |
---|---|
company_name | Type: String Required: Yes Minimum: 3 character Maximum: 128 characters. Description: The name of entity/business you want to search for documents. |
registration_number | Type: String Required: Yes Description: This parameter contains the registration number of the company being searched. |
country_name | Type: String 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. |
- Http
- Javascript
- PHP
- Python
- Node
- cURL
POST /api/getCountryPaidDocuments HTTP/1.1
Host: api.thekyb.com
Content-Type: application/json
Accept: application/json
token: YOUR_SECRET_KEY
{
"registration_number": "123456789",
"company_name": "XYZ Company Limited",
"country_name": "united_kingdom"
}
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({
registration_number: "123456789",
company_name: "XYZ Company Limited",
country_name: "united_kingdom",
});
var requestOptions = {
method: "POST",
headers: requestHeaders,
body: payload,
redirect: "follow",
};
fetch("https://api.thekyb.com/api/getCountryPaidDocuments", 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/api/getCountryPaidDocuments',
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 =>'{
registration_number: "123456789",
company_name: "XYZ Company Limited",
country_name: "united_kingdom"
}',
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/api/getCountryPaidDocuments"
payload = json.dumps({
"registration_number": "123456789",
"company_name": "XYZ Company Limited",
"country_name": "united_kingdom"
})
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'token': 'YOUR_SECRET_KEY'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
var axios = require("axios");
var data = JSON.stringify({
registration_number: "123456789",
company_name: "XYZ Company Limited",
country_name: "united_kingdom",
});
var config = {
method: "post",
url: "https://api.thekyb.com/api/getCountryPaidDocuments",
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/api/getCountryPaidDocuments' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'token: YOUR_SECRET_KEY' \
--data-raw '{
registration_number: "123456789",
company_name: "XYZ Company Limited",
country_name: "united_kingdom"
}'
Buy Documents
Description:
The "buyDocuments" API request allows users to purchase one or more documents by selecting them from the available options. Users need to specify the documents they wish to buy in the request.
The KYB platform offers two approaches for purchasing documents.
- First, users can directly purchase documents, retrieved from the Document Search response, where relevant documents related to the company can be purchase.
- Second, users can purchase documents as part of the KYB Check Service, where documents related to a business verification process are available.
Both methods give users flexibility in obtaining essential business records.
Method Call: POST
API:
https://api.thekyb.com/api/buyDocuments
Parameter | Description |
---|---|
company_id | Type: String Required: Optional Description: The company ID for the KYB Check is crucial when accessing and purchasing documents related to a company. In KYB Check version 1, to buy a document, you’ll need to provide the company_id , which is the _id obtained from the Enhanced Company Profile response.In KYB Check version 2, when buying a document for a company, the required company_id is actually the kyb_response_id , which can be found in the Detailed Company Insights response. Whether you're retrieving insights or purchasing documents, the kyb_response_id serves as the key identifier for the specific company. |
documents | Type: Array of Objects Required: Yes Description: An array of objects containing the unique identifiers for the documents. Each object includes the document's uid . If the document is for purchase previous document, include the previous_document_id in the object. |
documents.*.uid | Type: String Required: Yes Description: The unique identifier of the document. You can get uid of the document from Document Search endpoint response. Note: If you want to obtain a document related to a KYB Check Company, you can find the uid in the filings_detail key, which is provided in Enhanced Company Profile response. |
documents.*.previous_document_id | Type: String Required: No Description: This parameter contains the unique identifier of the previous document. The previously purchased document is available in our database. A 50% discount can be applied by opting for the older document using its document _id , which can be found in the previous_file_detail object within the document. Here is the Document Search endpoint for reference. Note: In KYB Check version 1, to obtain a document related to a KYB Check Company, locate the _id in the previous_file_detail object within the filings_detail key provided in the Enhanced Company Profile response.In KYB Check version 2, the previous_file_id can be found in the previous_file_detail object within the documents_detail key of the Detailed Company Insights response. |
- Http
- Javascript
- PHP
- Python
- Node
- cURL
POST /api/buyDocuments HTTP/1.1
Host: api.thekyb.com
Content-Type: application/json
Accept: application/json
token: YOUR_SECRET_KEY
{
"documents": [
{
"uid": "DOCUMENT UID"
},
{
"uid": "DOCUMENT UID",
"previous_document_id" : "_ID" // You can retrieve it from the previous_file_detail of the document object.
}
]
}
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({
"documents": [
{
"uid": "DOCUMENT UID"
},
{
"uid": "DOCUMENT UID",
"previous_document_id": "_ID" // You can retrieve it from the previous_file_detail of the document object.
}
]
});
var requestOptions = {
method: "POST",
headers: requestHeaders,
body: payload,
redirect: "follow",
};
fetch("https://api.thekyb.com/api/buyDocuments", 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/api/buyDocuments',
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 =>'{
"documents": [
{
"uid": "DOCUMENT UID",
"previous_document_id": "_ID" // You can retrieve it from the previous_file_detail of the document object.
}
]
}',
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/api/buyDocuments"
payload = json.dumps({
"documents": [
{
"uid": "DOCUMENT UID",
"previous_document_id": "_ID" // You can retrieve it from the previous_file_detail of the document object.
}
]
})
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'token': 'YOUR_SECRET_KEY'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
var axios = require("axios");
var data = JSON.stringify({
"documents": [
{
"uid": "DOCUMENT UID",
"previous_document_id": "_ID" // You can retrieve it from the previous_file_detail of the document object.
}
]
});
var config = {
method: "post",
url: "https://api.thekyb.com/api/buyDocuments",
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/api/buyDocuments' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'token: YOUR_SECRET_KEY' \
--data-raw '{
"documents": [
{
"uid": "DOCUMENT_UID",
"previous_document_id": "_ID" // You can retrieve it from the previous_file_detail of the document object.
}
]
}'
Read Document Service Details
Description:
The "Read Document Service Details" API enables users to retrieve detailed information about the requested document.
Method Call: GET
API:
https://api.thekyb.com/api/readDocumentsDetail?document_request_id=DOCUMENT_REQUEST_ID
Parameter | Description |
---|---|
document_request_id | Type: String Required: Yes Description: A unique identifier for the document request. This ID is used to track the document request throughout the process. You can obtain the document_request_id from the response of the Buy Documents endpoint. |
- Http
- Javascript
- PHP
- Python
- Node
- cURL
GET /api/readDocumentsDetail?document_request_id=DOCUMENT_REQUEST_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/api/readDocumentsDetail?document_request_id=DOCUMENT_REQUEST_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/api/readDocumentsDetail?document_request_id=DOCUMENT_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;
import requests
import json
url = "https://api.thekyb.com/api/readDocumentsDetail?document_request_id=DOCUMENT_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)
var axios = require("axios");
var config = {
method: "get",
url: "https://api.thekyb.com/api/readDocumentsDetail?document_request_id=DOCUMENT_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 --location --request GET 'https://api.thekyb.com/api/readDocumentsDetail?document_request_id=DOCUMENT_REQUEST_ID' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'token: YOUR_SECRET_KEY'
Response
The Paid Document Extraction API offers two types of responses when a document search 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 search 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/getDocumentCountries
Response:
{
"error": false,
"message": "Paid documents countries fetched successfully",
"data": {
"countries": [
"armenia",
"australia",
"austria",
"belarus",
"brunei",
....
]
}
}
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. |
Document Search
Description:
When users perform a document search using the "getCountryPaidDocuments" API, the response will provide user a list of documents of searched company. For example, if a user searches for a document related to the company name "Apple" within the United States, the API will provide the document details matching the search criteria.
API:
https://api.thekyb.com/api/getCountryPaidDocuments
Response:
{
"error": false,
"message": "Paid documents fetched successfully",
"data": {
"paid_documents": [
{
"uid": "9b0b8a074395b763df1e1a5c58dbd",
"title": "Company statement of register",
"price": "$15.22",
"price_without_service_charges": "$12.68",
"service_charges": "$2.54",
"deliver_time": "4-5 working days",
"previous_file_detail": {
"_id": "66ebcfd4e0b69f10e9025",
"uid": "9b0b8a074395b763df1e1a5c58dbd",
"submitted_at": "2024-09-19T07:16:36.248000Z",
"price": "$7.61",
"price_without_service_charges": "$6.34",
"service_charges": "$1.27"
},
"own_document_available": {
"_id": "66ea78d2ff8383535106f",
"uid": "9b0b8a074395b763df1e1a5c58dbd",
"submitted_at": "2024-09-18T06:53:14.091000Z",
"requested_at": "2024-09-18T06:53:06.024000Z",
"file_url": "https://api.thekyb.com/api/get-file/65b8ff11e583c436440fa/66ea78dada2f0de504029?expires=1726733667&signature=8ca7378614207d9ea94aa0e86f1034ac18438239ebb7875d5f76c984a8d19"
}
}
]
}
}
Response Parameters:
Parameter | Description |
---|---|
error | The "error" parameter indicates whether the request encountered any errors. In this case, it is set to false , meaning the request was successful. If an error had occurred, this would be set to true . |
message | The "message" parameter provides a status message about the request. |
data.paid_documents | Contains information about paid documents available for purchase. |
data.paid_documents.*.uid | A unique identifier for each document. |
data.paid_documents.*.title | The title of the document, providing information on what the document pertains to. |
data.paid_documents.*.price | The total price for the document, including service charges. |
data.paid_documents.* .price_without_service_charges | The base price of the document, excluding service charges. |
data.paid_documents.*.service_charges | The amount charged as a service fee. |
data.paid_documents.*.deliver_time | The estimated delivery time for the document. |
data.paid_documents.* .previous_file_detail._id | A unique identifier for the previously submitted file associated with this document. |
data.paid_documents .previous_file_detail.uid | The unique identifier of document. |
data.paid_documents .previous_file_detail.submitted_at | The timestamp indicating when the own document was submitted. |
data.paid_documents.* .previous_file_detail.price | The price for the previous document file. |
data.paid_documents.*.previous_file_detail. price_without_service_charges | The price of the previous document file excluding service charges. |
data.paid_documents.* .previous_file_detail.service_charges | The service charges applied to the previous document file. |
data.paid_documents.* .own_document_available | Contains details of a previously purchased document by the user |
data.paid_documents.* .own_document_available._id | A unique identifier for a document available for the current user. |
data.paid_documents .own_document_available.uid | The unique identifier of document. |
data.paid_documents .own_document_available.submitted_at | The timestamp indicating when the document was submitted. |
data.paid_documents .own_document_available.requested_at | The timestamp indicating when the document was requested. |
data.paid_documents.* .own_document_available.file_url | The URL to download the document that is available for the user. |
Buy Documents
Description:
The "buyDocuments" response informs the user that the service was created successfully along with requested document details.
API:
https://api.thekyb.com/api/buyDocuments
Response:
{
"error": false,
"message": "Documents requested successfully",
"data": {
"document_request_id": "DOCUMENT_REQUEST_ID",
"service_id": "SERVICE_ID",
}
}
Response Parameters:
Parameter | Description |
---|---|
error | The "error" parameter indicates whether there was an error during the request. In this case, it is false , meaning the request was successful. |
message | The "message" parameter provides feedback about the request. |
data.document_request_id | A unique identifier for the requested document. This ID helps track the document request. |
data.service_id | The service_id represents the unique identifier of the service linked to the document request. |
Read Document Service Details
Description:
The "Read Document Service Details" response provides users with detailed information about the requested document.
API:
https://api.thekyb.com/api/readDocumentsDetail?document_request_id=DOCUMENT_REQUEST_ID
Response:
{
"error": false,
"message": "Paid documents service detail fetched successfully",
"data": {
"document_request": {
"_id": "66ebf942054a77c3c0014",
"service_id": "66ebf942054a77c3c0014",
"documents": [
{
"uid": "b76e62e5641b9b1530ff9b9d6251b"
}
],
"status": "pending",
"updated_at": "2024-09-19T10:13:22.742000Z",
"created_at": "2024-09-19T10:13:22.742000Z",
"requested_document_ids": [
"66ebf9451b2125025707b"
]
},
"documents_response_detail": [
{
"_id": "66ebf9451b2125025707b",
"uid": "b76e62e5641b9b1530ff9b9d6251b",
"title": "annual return",
"price": "$3.05",
"deliver_time": "4-5 working days",
"document_status": "resolved",
"file_url": "https://api.thekyb.com/api/get-file/65b8ff11e583c436440fa/66ebfa0936fa8c4cc40e6?download=1&expires=1726741678&log=0&signature=c704e65f498690044e4f395f1760437908574ce55699aa81666555c22c397",
"document_not_found": false
}
]
}
}
Response Parameters:
Parameter | Description |
---|---|
error | Indicates whether there was an error during the request. In this case, it is false , meaning the request was successful. |
message | The "message" parameter provides feedback about the request. |
data.document_request._id | The unique identifier for the document request. |
data.document_request.service_id | The service id associated with the document request. |
data.document_request.documents | Contains an array of requested documents. |
data.document_request. documents.*.uid | The unique identifier of the document. This value can be used to reference or retrieve the specific document from the system. |
data.document_request.status | The current status of the document request."status": "pending" indicates that the request is still in progress and has not yet been completed. "status": "resolved" indicates the completion of service request. |
data.document_request.updated_at | The timestamp when the document request was last updated. |
data.document_request.created_at | The timestamp when the document request was created. |
data.document_request. requested_document_ids | An array containing the IDs of the documents that were requested. |
data.documents_response_detail | Contains the response of the documents requested. It also provides information on whether the document was submitted or not and the URL for downloading the document if available. |
data.documents_response_detail.*._id | The unique identifier for the document in the response. |
data.documents_response_detail.*.uid | The unique identifier of the document. This value can be used to reference the specific document from the system. |
data.documents_response_detail.*.name | The name of the document. |
data.documents_response_detail.*.price | The price of the document. |
data.documents_response_detail. *.document_status | The current status of the document request. "pending" indicates that the document is still in progress and has not yet been submitted. "resolved" indicates that the document has been submitted, whether the document was found or not found. |
data.documents_response_detail.*.deliver_time | The estimated delivery time for the document. |
data.documents_response_detail.*.file_url | The URL to download or access the document file. |
data.documents_response_detail. *.document_not_found | Indicates whether the document was found or not. If false , the document is available in The KYB. If true , the document is not available. |