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

GET {{API_URL}}/v1.4/ping
Example Request
Example Response
200 OK

Generate Token

POST {{API_URL}}/v1.4/genToken
HEADERS
Content-Type
application/x-www-form-urlencoded
BODY urlencoded

Request Payload


Key Value
username {{username}}
required
password {{password}}
required

Example Request
Example Response
200 OK

Token Authentication

GET {{API_URL}}/v1.4/auth
HEADERS
Authorization
Bearer {{token}}
Example Request
Example Response
200 OK

Company Search

POST {{API_URL}}/v1.4/search
HEADERS
Authorization
Bearer {{token}}
Content-Type
application/x-www-form-urlencoded
BODY urlencoded

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

company_name
:
Neuralink
request_id
:
0001
country_code
:
US
source
:
1
Example Request
Example Response
200 OK

Officer Search

POST {{API_URL}}/v1.4/officer/search
HEADERS
Authorization
Bearer {{token}}
Content-Type
application/x-www-form-urlencoded
BODY urlencoded

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
Note :
*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

officer_name
:
Ratan Tata
request_id
:
0001
country_code
:
IN
source
:
1

Example Request
Example Response
200 OK

Company Details

POST {{API_URL}}/v1.4/details
HEADERS
Authorization
Bearer {{token}}
Content-Type
application/x-www-form-urlencoded
BODY urlencoded

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
Note :
*State is mandatory for US, CA, UAE.
*Either gst_number or company_number is required for country INDIA

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

company_name
:
facebook
request_id
:
0001
country_code
:
US
state
:
NM
source
:
1
company_number
:
6055958

Example Request
Example Response
200 OK