Skip to main content

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
GET /api/getDocumentCountries HTTP/1.1
Host: api.thekyb.com
Content-Type: application/json
Accept: application/json
token: YOUR_SECRET_KEY

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
ParameterDescription
company_nameType: String
Required: Yes
Minimum: 3 character
Maximum: 128 characters.
Description: The name of entity/business you want to search for documents.
registration_numberType: String
Required: Yes
Description: This parameter contains the registration number of the company being searched.
country_nameType: 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.
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"
}

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.

info

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
ParameterDescription
company_idType: 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.
documentsType: 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.*.uidType: 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_idType: 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.
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.
}
]
}

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
ParameterDescription
document_request_idType: 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.
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

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:

ParameterDescription
errorThe "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."
messageThe "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.
dataThe "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.countriesThe "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:

ParameterDescription
errorThe "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.
messageThe "message" parameter provides a status message about the request.
data.paid_documentsContains information about paid documents available for purchase.
data.paid_documents.*.uidA unique identifier for each document.
data.paid_documents.*.titleThe title of the document, providing information on what the document pertains to.
data.paid_documents.*.priceThe 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_chargesThe amount charged as a service fee.
data.paid_documents.*.deliver_timeThe 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:

ParameterDescription
errorThe "error" parameter indicates whether there was an error during the request. In this case, it is false, meaning the request was successful.
messageThe "message" parameter provides feedback about the request.
data.document_request_idA unique identifier for the requested document. This ID helps track the document request.
data.service_idThe 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:

ParameterDescription
errorIndicates whether there was an error during the request. In this case, it is false, meaning the request was successful.
messageThe "message" parameter provides feedback about the request.
data.document_request._idThe unique identifier for the document request.
data.document_request.service_idThe service id associated with the document request.
data.document_request.documentsContains 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.statusThe 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_atThe timestamp when the document request was last updated.
data.document_request.created_atThe 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_detailContains 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.*._idThe unique identifier for the document in the response.
data.documents_response_detail.*.uidThe unique identifier of the document. This value can be used to reference the specific document from the system.
data.documents_response_detail.*.nameThe name of the document.
data.documents_response_detail.*.priceThe 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_timeThe estimated delivery time for the document.
data.documents_response_detail.*.file_urlThe 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.