IDMkyb
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)
Overview
IDM Kyb service is verify instantly business identities,
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.
IDM kyb helps you to:
- Identify Corporate Data To Prevent Fraud
- Recieve Best-In-Industry Match Rates
- Remain KYB Compliant
- Scale Existing Compliance Programs
- Quickly Onboard New Business Customers
Getting Started
If you have any questions or comments, please let us know via our Support Portal.
Knowledge Base
COMMUNICATION METHODOLOGY
The IDM kyb API methodology is organized into four main sections:
- End-Point Test Method enables you to verify the accessibility of our API.
- Token Generation Method enables you to generate the access token using the provided credentials. The time period that the Token will be valid is determined by IDMERIT.
- Authentication Test Method enables you to verify the validity of the assigned credentials.
- Search method enable you to get/fetch the details of the companies and the employees associated with it on that particular details
AUTHENTICATION METHODOLOGY
As stated above, the IDM kyb API authentication framework is built upon token-based authentication:
- The Username and Password provided by IDMERIT to the Client.
- The user and password posted to IDM kyb API via to request the API to receive an encoded access Token.
- This token must be used in all subsequent Authorization headers from the Client side API.
Country Code Format
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
API parameters:
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.
As below are the required fields FOR COMPANY DETAILS:
- company_name:
- company_number:
- country_code:
- request_id:
Result:
Company name :
- Incorporation date:
- Address:
- Country:
- Employee’s details: name, designation,id.
- Parent company info
- Filing Information
- UBO UCC info
ERROR CODES
HTTP Error Codes
| 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. |
SOURCE/OTHER ERRORS
Please contact our support team at https://idmerit.freshdesk.com/support/tickets/new
API Description
Ping Test
curl -X GET \
'{{API_URL}}/v1.4/ping'{
"status": true,
"status_code": 200,
"message": "Successfully Connected."
}
Content-Type: application/jsonGenerate 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/jsonToken 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/jsonCompany 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 |
Response
| 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. |
Example
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/jsonOfficer 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 |
*State is mandatory for US, CA, UAE.
Response
| 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. |
Example
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/jsonCompany 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 |
*State is mandatory for US, CA, UAE.
Response
| 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. |
Example
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