Business Verification

For the list of supported countries and search types, please check this section of the documentation.

Overview

The business verification product lets you search the business registration or tax information (available in Nigeria only) of a business from one of our supported countries. The business registration search will return the company information, directors, beneficial owners and fiduciaries of a business while the tax information returns only the company information.

Integration Options

Only available using Rest APIs.

Asynchronous vs Synchronous

This API is available as both an Asynchronous API (recommended) which guarantees an eventual response regardless of ID authority availability and as a Synchronous API to be used in real time environments such as mobile applications which does not guarantee a response in the case that an ID authority is unavailable. For high volume applications the Asynchronous API is required. If you are using the Asynchronous API you must have a callback endpoint in your request where the response will be delivered. The urls for the endpoints are:

Asynchronous

Environment	URL
Sandbox:	https://testapi.smileidentity.com/v1/async_business_verification
Production:	https://api.smileidentity.com/v1/async_business_verification

Synchronous

Environment	URL
Sandbox:	https://testapi.smileidentity.com/v1/business_verification
Production:	https://api.smileidentity.com/v1/business_verification

Request Values

The Enhanced KYC API has the following input parameters which should be contained in a JSON body object submitted to the endpoint

Request Type: Post

Name	Type	Required	Description
partner_id	string	Yes	A unique number assigned by Smile ID to your account. Can be found with your API key here
source_sdk	string	Yes	The integration option you are using. For rest api send the value as "rest_api"
source_sdk_version	string	Yes	The version of the integration option you are using. For rest api send the value as “1.0.0”
signature	string	Yes	The outgoing signature to authenticate the request from you to Smile ID
timestamp	string	Yes	The timestamp used to calculate the signature in ISO date/time format
callback_url	string	Yes for Async	Your callback url, results of jobs will be sent to the specified url. You can read more about callback urls here
country	string	Yes	The country where the business is incorporated. Link to country codes here.
id_type	string	Yes	The search type you want to query. BASIC_BUSINESS_REGISTRATION or BUSINESS_REGISTRATION orTAX_INFORMATION
id_number	string	Yes	The business registration number (for Business_Registration or Basic_Business_Registration search) or tax identification number (for Tax_Information search)
business_type	string	Only required for BASIC_BUSINESS_REGISTRATION and BUSINESS_REGISTRATION in Nigeria	The business incorporation type bn - business name co - private/public limited it - incorporated trustees
postal_code	string	Only required for BUSINESS_REGISTRATION in Kenya	The postal code of the business (must be a 5 digit string)
postal_address	string	Only required for BUSINESS_REGISTRATION in Kenya	The postal code of the business (must be a 4 or 5 digit string)
partner_params	object	Yes	A JSON object containing the partner parameters below as well as any additional key value pairs you wish to include for tracking which will be returned in the response
job_type	string	Yes	The type of job you want to perform. This will be set to 7.
job_id	string	Yes	A value generated by you, so you can track jobs on your end. This value must be unique, can be any string and can follow your identifier convention
user_id	string	Yes	A unique value generated by you, so you can track all jobs related to a business on your end. You can re-use a user_id but we recommend you only do so if you are running another job related to the same business

Example JSON Body

{
  "business_type": "co",
  "callback_url": "example.site",
  "country": "NG",
  "id_number": "0000000",
  "id_type": "BUSINESS_REGISTRATION",
  "partner_id": "001",
  "partner_params": {
    "job_id": "001",
    "job_type": 7,
    "user_id": "kyb_test_user_008"
  },
  "signature": "---",
  "source_sdk": "rest_api",
  "source_sdk_version": "1.0.0",
  "timestamp": "2023-10-17T11:32:36.515Z"
}

Return Values

The business verification product can potentially return 6 categories of information depending on the search type, business incorporation type or information available in the business registration agency’s database. The full list of possible response from a business verification is listed below:

Name	Type	Description	Return Values
SmileJobID	string	The Smile internal reference number for the job. Please include this when contacting support on a job.
PartnerParams.job_id	string	A unique reference defined by you to keep track of the job
PartnerParams.job_type	string	The type of job you performed	“7”
PartnerParams.user_id	string	A unique reference defined by you to keep track of the user
signature	string	The outgoing signature, you can use this to verify that the response is from Smile ID
timestamp	string	The outgoing timestamp in ISO date/time format, use this to calculate the outgoing Signature
ResultText	string	Textual value of the job outcome. Human readable value for the result	Full list of result text in our documentation.
ResultCode	string	Numeric value of the job outcome	For a list of potential result codes see here.
Actions	object	A JSON object containing the details of the individual field comparisons
Verify_Business	string	The result of looking up the ID number in the ID authority database is returned in this key	"Verified" "Not Verified" "Not Done" "Issuer Unavailable"
Return_Business_Info	string	This key confirms if we sent the personal information retrieved from the ID authority sent to you	"Returned" "Not Returned" "Not Applicable"
company_information	object	A JSON object containing basic information about the company
company_type	string	The company’s type of incorporation
country	string	The country where the business is registered
address	string	The address filed at the registration agency
registration_number	string	The company’s registration number
search_number	string	The number passed in the id_number field when the business verification request was made
authorized_shared_capital	string	The authorized share capital, allocated during company incorporation
industry	string	The type of industry the business is in
tax_id	string	The tax id number of the business
registration_date	string	The date the business was registered
phone	string	The contact phone number of the business
legal_name	string	The legal name of the business
state	string	The state/county/province where the business is located
email	string	The contact email address of the business
status	string	The status of the business
directors	array	A JSON array of objects containing information about the directors
shareholdings	string	The amount of shares held by the director
id_number	string	The id number of the document submitted by the director during incorporation
address	string	The address of the director filed at the registration agency
occupation	string	The role of the director in the company
gender	string	The gender of the director
nationality	string	The nationality of the director
date_of_birth	string	The date of birth of the director
name	string	The full name of the director
id_type	string	The document type submitted by the director during incorporation
phone_number	string	The phone number of the director
proprietors	array	A JSON array of objects containing information about the proprietors of the business. Only returned for sole proprietorship
id_number	string	The id number of the document submitted by the proprietor during incorporation
address	string	The address of the proprietor filed at the registration agency
occupation	string	The role of the proprietor in the company
gender	string	The proprietor of the director
nationality	string	The nationality of the proprietor
date_of_birth	string	The date of birth of the proprietor
name	string	The full name of the proprietor
id_type	string	The document type submitted by the proprietor during incorporation
phone_number	string	The phone number of the proprietor
beneficial_owners	array	A JSON array of objects containing information about the shareholders and other beneficial owners of the business
shareholdings	string	The amount of shares held by the beneficial owner
address	string	The address of the beneficial owner filed at the registration agency
gender	string	The gender of the beneficial owner
nationality	string	The nationality of the beneficial owner
registration_number	string	The registration number of beneficial owner. Only returned if the beneficial owner is an organization.
name	string	The full name of the beneficial owner
shareholder_type	string	The type of beneficial owner
phone_number	string	The phone number of the beneficial owner
fiduciaries	array	A JSON array of objects containing information about the fiduciaries of the business
name	string	The full name of the fiduciary
fiduciary_type	string	The fiduciary type
address	string	The address of the fiduciary
registration_number	string	The registration number of the fiduciary. Only returned if the fiduciary is an organization
status	string	The status of the fiduciary
documents	object	A JSON object containing documents related to the company’s incorporation
search_certificate	string	A base 64 encoded image string containing the business’ registration information

Example JSON Response

{
  "signature": "---",
  "timestamp": "2022-10-17T10:46:49.392Z",
  "SmileJobID": "0000001927",
  "PartnerParams": {
    "user_id": "kyb_test_user_008",
    "job_id": "001",
    "job_type": 7
  },
  "ResultText": "Business Verified",
  "ResultCode": "1012",
  "Actions": {
    "Return_Business_Info": "Returned",
    "Verify_Business": "Verified"
  },
  "company_information": {
    "company_type": "PRIVATE_COMPANY_LIMITED_BY_SHARES",
    "country": "Nigeria",
    "address": "10, Workbox, Ojora Close, Victoria Island, Lagos",
    "registration_number": "0000000",
    "search_number": "0000000",
    "authorized_shared_capital": "10000000",
    "industry": "Technology Solutions Company",
    "tax_id": "N/A",
    "registration_date": "2016-01-28T16:06:22.003+00:00",
    "phone": "08000000000",
    "legal_name": "SMILE IDENTITY NIGERIA LIMITED",
    "state": "LAGOS",
    "email": "[e-mail]",
    "status": "Verified"
  },
  "fiduciaries": [
    {
      "name": "Company X",
      "fiduciary_type": "SECRETARY_COMPANY",
      "address": "10, Workbox, Ojora Close, Victoria Island, Lagos",
      "registration_number": "000000",
      "status": "N/A"
    }
  ],
  "beneficial_owners": [
    {
      "shareholdings": "100000",
      "address": "10, Workbox, Ojora Close, Victoria Island, Lagos",
      "gender": "Male",
      "nationality": "Nigerian",
      "registration_number": "N/A",
      "name": "Joe Bloggs",
      "shareholder_type": "Individual",
      "phone_number": "0123456789"
    },
    {
      "shareholdings": "700000",
      "address": "1234 Main Street Anytown Anystate 00000 USA",
      "gender": "Not Applicable",
      "nationality": "N/A",
      "registration_number": "000000",
      "name": "XYZ Widget Corporation",
      "shareholder_type": "Corporate",
      "phone_number": "0123456789"
    }
  ],
  "proprietors": [],
  "documents": {
    "search_certificate": ""
  },
  "directors": [
    {
      "shareholdings": "100000",
      "id_number": "A000000",
      "address": "10, Workbox, Ojora Close, Victoria Island, Lagos",
      "occupation": "CEO",
      "gender": "MALE",
      "nationality": "Nigerian",
      "date_of_birth": "2000-09-20",
      "name": "Joe Doe Leo",
      "id_type": "Passport",
      "phone_number": "0123456789"
    },
    {
      "shareholdings": "100000",
      "id_number": "A000000",
      "address": "1234 Main Street Anytown Anystate 00000 USA",
      "occupation": "COO",
      "gender": "FEMALE",
      "nationality": "American",
      "date_of_birth": "2000-01-01",
      "name": "Jane Doe",
      "id_type": "Passport",
      "phone_number": "0123456789"
    }
  ],
  "success": true
}

Evaluating the Results

The result of the business verification search can be interpreted using the result code. For successful calls, we recommend you compare the returned values for the fields against the user submitted information. The full list of result codes and texts are available below.

Result Codes and Result Texts

Result codes details what the result of a job is. Result Codes for all jobs fall into one of two categories:

1. Approved (or Pass) This means that all applicable Actions passed and the overall job was approved.

2. Rejected (or Fail) This means that one or more of the applicable Actions for job failed, and thus, the overall job was rejected according to Smile ID standards.

General Failures Result Codes and Texts

This means no further processing is possible on the job. General failures occur when a job could not be submitted due to a logical/technical issue. These jobs do not show up in the portal and do not have a Smile Job ID.

Code	Text	Description	Category
0001	Data Invalid
2405	Error - "You are not authorized to do that" *	An invalid signature was used to sign the request.
2205	Error - You are not authorized to do that. *	An invalid signature was used to sign the request.
2213	Error - A required parameter is missing	Not all the required keys were submitted in the info.json or request payload. Please check request values for this search type.
2204	Error - A parameter is of the wrong data type	The format of one of the request values was wrong. Please check request values for this search type.
2220	Error - Production is not enabled for this account. Please complete your KYC.	You have not completed your KYC.
2212	Error - Invalid job type **	An invalid value was inputted in the job_type key. Change the value to "7".
2413	Error: Unsupported ID number format Error: Unsupported ID type Error: Unsupported business type (for NG BUSINESS_REGISTRATION and BASIC_BUSINESS_REGISTRATION)	The ID number submitted was of an invalid format. Please use our regex samples as a guide The ID type inputted ID type is invalid The business_type is invalid. Please input one of the supported business_types

* - read more on how to troubleshoot this error here

Product Specific Result Codes and Texts

Code	Text	Description	Category
1012	Business Verified	The search info was found in the authority’s database.	Approved
1013	Unable to Verify Business - Not Found	The search info was not found in the authority’s database.	Rejected
1015	Unable to Verify Business - Queried Database Unavailable	The registration or tax agency is unavailable.	Not Processed
1016	Unable to Verify Business - Need to Activate Product	You do not have access to the search type. Please contact support for more information.	Not Processed