v1.4.0 Updated: Friday, october 28, 2022
Welcome to the IDMkyb RESTful API. You can use our API to access all of IDMkyb's services.
TEST URL: {{API_URL}} (All the examples in this documentation are based on Test Environment)
Utilizing an API (REST), IDMkyb streamlines the compliance process by making the onboarding of business customers and partners run much more smoothly while mitigating risk and reducing fraud. Due to worldwide efforts to fight fraud, tax evasion and other criminal activities, additional legal requirements for verifying businesses have been instituted.
If you have any questions or comments, please let us know via our Support Portal.
The IDM kyb API methodology is organized into four main sections:
As stated above, the IDM kyb API authentication framework is built upon token-based authentication:
We support only ISO 3166-1 alpha 2 country codes. Please visit https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 to know more about country codes
KYB Company Search: You will be able to search & filter a list of companies based on different search criteria.
KYB Company Details: You can get the details of a particular company.
Here we can get the complete data of the companies which have the name and company number as input data.
Along with the name of the company, incorporated date, status of the company, address of the company, and the details of the employees of the company along with their designation.
Information OF the Companies on the requested data will be shared with the KYB info service.
Here we can get the complete data of the companies which have the similar name as input data.
Along with the name of the company, incorporated date, status of the company, address of the company, and the details of the employees of the company along with their designation.
Company name :
Code | Description |
---|---|
200 - OK | The request was successful. If you are getting unexpected results, please check any Status or Error messages that have been returned in the response. If you believe there may be a problem, please raise a ticket with our Support team at https://idmerit.freshdesk.com/support/tickets/new. |
400 - Bad Request | The request could not be understood by the server. Please ensure the request is in the appropriate format and all necessary headers have been included. |
403 - Forbidden | The request was valid, but the requestor does not have appropriate permissions. Please ensure your username is correct and your access token is still valid. If your access token has expired, you may need to reauthenticate your credentials to get a new token. |
415 - Unsupported Media Type | The request entity has a media type which the server or resource does not support. For example, the client uploads an image as image/svg+xml, but the server requires that images use a different format. |
500 - Internal Server Error | There was a back-end error when processing the request. Please ensure your request is in the correct format and retry. If you receive this error again, please raise a ticket with our Support team at https://idmerit.freshdesk.com/support/tickets/new. |
522 - Origin Connection Time-out | There was a back-end error when processing the request. Please resubmit the request. If you receive this error again, please raise a ticket with our Support team at https://idmerit.freshdesk.com/support/tickets/new. |
Please contact our support team at https://idmerit.freshdesk.com/support/tickets/new
Ping Test
curl -X GET \
'{{API_URL}}/v1.4/ping'
{
"status": true,
"status_code": 200,
"message": "Successfully Connected."
}
Content-Type: application/json
Generate Token
Request Payload
Key | Value | |
---|---|---|
username |
{{username}} |
required |
password |
{{password}} |
required |
curl -X POST \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'username={{username}}' \
-d 'password={{password}}' \
'{{API_URL}}/v1.4/genToken'
{
"status": true,
"status_code": 200,
"issued": "{{issued}}",
"expires": "{{expires}}",
"access_token": "{{access_token}}",
"token_type": "bearer",
"username": "{{username}}"
}
Content-Type: application/json
Token Authentication
curl -X GET \
-H 'Authorization: Bearer {{token}}' \
'{{API_URL}}/v1.4/auth'
{
"status": true,
"status_code": 200,
"message": "Token is valid.",
"expired_at": "{{expired_at}}"
}
Content-Type: application/json
Company Search
Request Payload
Key | Value | |
---|---|---|
company_name |
{{company_name}} |
required |
country_code |
{{country_code}} |
required |
source |
{{source}} |
optional |
request_id |
{{request_id}} |
required |
state |
{{state}} |
optional |
Key | value |
---|---|
company_name |
The legal name of the company from company registry. |
reg_num |
The identifier is given to the company by the company register/registry. |
gst_number |
The unique goods and service Tax identification number given to the company. (note: for INDIA country). |
country |
ISO two-digit country code/name in which the company is located. |
state |
ISO two-digit country code/name in which the company is located for US/CA/UAE. |
curl -X POST \
-H 'Authorization: Bearer {{token}}' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'company_name={{company_name}}' \
-d 'country_code={{country_code}}' \
-d 'source={{source}}' \
-d 'request_id={{request_id}}' \
-d 'state={{state}}' \
'{{API_URL}}/v1.4/search'
{
"status": true,
"status_code": 200,
"data": [
{
"company_name": "{{company_name1}}",
"reg_number": "{{reg_number}}",
"country": "{{country}}",
"state": "{{state}}",
"current_status":"{{current_status}}",
"branch":"{{branch}}",
"address":"{{address}}"
},
{
"company_name": "{{company_name2}}",
"reg_number": "{{reg_number}}",
"country": "{{country}}",
"state": "{{state}}",
"current_status":"{{current_status}}",
"branch":"{{branch}}",
"address":"{{address}}"
},
{
"company_name": "{{company_name3}}",
"reg_number": "{{reg_number}}",
"country": "{{country}}",
"state": "{{state}}",
"current_status":"{{current_status}}",
"branch":"{{branch}}",
"address":"{{address}}"
},
{
"company_name": "{{company_name4}}",
"reg_number": "{{reg_number}}",
"country": "{{country}}",
"state": "{{state}}",
"current_status":"{{current_status}}",
"branch":"{{branch}}",
"address":"{{address}}"
},
{
"company_name": "{{company_name5}}",
"reg_number": "{{reg_number}}",
"country": "{{country}}",
"state": "{{state}}",
"current_status":"{{current_status}}",
"branch":"{{branch}}",
"address":"{{address}}"
},
{
"{{company_name6}}",
"reg_number": "{{reg_number}}",
"country": "{{country}}",
"state": "{{state}}",
"current_status":"{{current_status}}",
"branch":"{{branch}}",
"address":"{{address}}"
},
{
"
},
{
.
.
.
.
.
.
.
.
},
{
"company_name": "{{company_name(n)}}",
"reg_number": "{{reg_number}}",
"country": "{{country}}",
"state": "{{state}}",
"current_status":"{{current_status}}",
"branch":"{{branch}}",
"address":"{{address}}"
},
{
}
],
"transaction_id": "16475xxxxxx233f02dexxxxxxCse",
"request_id": "{{request_id}}"
}
Content-Type: application/json
Officer Search
Request Payload
Key | Value | |
---|---|---|
officer_name |
{{officer_name}} |
required |
country_code |
{{country_code}} |
required |
request_id |
{{request_id}} |
required |
source |
{{source}} |
optional |
state |
{{state}} |
optional |
officer_id |
{{officer_id}} |
required only for country ARGENTINA |
Key | value |
---|---|
Name |
Name of the officer |
Position |
the role in which the officer holds in the organization/company |
officer_id |
It is the id provided to the officer by the company office registry. |
actd_company |
company name in which the officer is associated with. |
actd_regnumber |
The identifier is given to the company by the company register/registry for the associated company. |
country |
ISO two-digit country code/name in which the company is located. |
state |
ISO two-digit country code/name in which the company is located for US/CA/UAE. |
curl -X POST \
-H 'Authorization: Bearer {{token}}' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'officer_name={{officer_name}}' \
-d 'country_code={{country_code}}' \
-d 'request_id={{request_id}}' \
-d 'source={{source}}' \
-d 'state={{state}}' \
-d 'officer_id={{officer_id}}' \
'{{API_URL}}/v1.4/officer/search'
{
"status": true,
"status_code": 200,
"data": [
{
"name": "{{name}}",
"position": "{{position}}",
"officer_id": "{{officer_id}}",
"actd_company": "{{companyname}}",
"actd_regnumber": "{{company reg_number}}",
"country": "{{country_code}}",
"state": "{{state}}"
},
{
"name": "{{name}}",
"position": "{{position}}",
"officer_id": "{{officer_id}}",
"actd_company": "{{companyname}}",
"actd_regnumber": "{{company reg_number}}",
"country": "{{country_code}}",
"state": "{{state}}"
},
{
"name": "{{name}}",
"position": "{{position}}",
"officer_id": "{{officer_id}}",
"actd_company": "{{companyname}}",
"actd_regnumber": "{{company reg_number}}",
"country": "{{country_code}}",
"state": "{{state}}"
}
],
"transaction_id": "{{16475xxxxxx233f02dexxxxxxCse}}",
"request_id": "{{request_id}}"
}
Content-Type: application/json
Company Details
Request Payload
Key | Value | |
---|---|---|
company_name |
{{company_name}} |
required |
company_number |
{{company_number}} |
required |
country_code |
{{country_code}} |
required |
request_id |
{{request_id}} |
required |
source |
{{source}} |
optional |
state |
{{state}} |
optional |
Key | value |
---|---|
company_name |
The Legal Name of the company |
reg_number |
The unique identifier is given to the company by the company register/registry. |
gst_number |
The unique goods and service Tax identification number given to the company. (note: for INDIA country). |
incorporation_date |
is the date registered when the company is started/ incorporated. note: not all company registers record and publish this date. |
dissolution_date |
Is the date of dissolution/closure and as given by the company register.note: not all company registers record and publish this data. |
type |
it populates the type of the company (i.e. limited liability company, limited by shares, private limited, GBMH, public shares limited, etc.) |
current_status |
Status of the company whether the company is active/ inactive/dissolved/unknown in for the filing! |
branch |
It provided whether the search company is a branch or not. It is a Boolean value of True/False. |
parent_company_info |
It provides the parent company information for the given company. This will be populated when the info is available in the data registry. |
primary_company_info |
It is the parent holding control of the undertaking in question, and it is derived either from explicit data about the subsidiary or the parent company, or from an investee company having a majority equity shares in the company. |
ubo_info |
These are the ultimate beneficial owners of the company! ucc_info It's the parent company that holds the ultimate control of that company. This is the equivalent of the Primary Controlling Company |
complete_address |
The complete registered address of the company is in a single string. |
address_details |
The registered address of the company is a structured object. |
officers |
Officer's information who are associated with the company along with the designation. |
filing_info |
Latest filing information of the company lastly updated. |
curl -X POST \
-H 'Authorization: Bearer {{token}}' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'company_name={{company_name}}' \
-d 'company_number={{company_number}}' \
-d 'country_code={{country_code}}' \
-d 'request_id={{request_id}}' \
-d 'source={{source}}' \
-d 'state={{state}}' \
'{{API_URL}}/v1.4/details'
{
"status": true,
"status_code": 200,
"data": [
{
"company_name": "{{company_name}}",
"reg_number": "{{reg_number}}",
"incorporation_date": "{{incorporation_date}}",
"dissolution_date": "{{dissolution_date}}",
"type": "{{type}}",
"current_status": "{{current_status}}",
"branch": "{{branch}}",
"parent_company_info":
{
"company_name": "{{company_name}}",
"country_code": "{{country_code}}",
"reg_number": "{{reg_number}}"
},
"primary_company_info":
{
"company_name": "{{company_name}}",
"country_code": "{{country_code}}",
"reg_number": "{{reg_number}}"
},
"ubo_info": "{{ubo_info}}",
"ucc_info":
{
"uccname": "{{uccname}}",
"ucccountry": "{{us_de}}",
"uccregno": "{{3677166}}"
},
"complete_address": "{{complete_address}}",
"address_details": {
"address": "{{address}}",
"city": "{{city}}",
"state": "{{state}}",
"zip": "{{zip}}"
},
"officers": [
{
"name": "{{name}}",
"position": "{{position}}"
}
,
{
"name": "{{name}}",
"position": "{{position}}"
}
]
"filling":{
"last_filing_date":"{{last_filing_date}}"
"filing_type"{
"filing_type_code":"{{filing_type_code}}"
"filing_type_description":"{{filing_type_description}}"
}
}
}],
"transaction_id": "{{transaction_id}}",
"request_id": "{{request_ids}}"
}
Content-Type: application/json