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

EnvironmentURL

Sandbox:

https://testapi.smileidentity.com/v1/async_business_verification

Production:

https://api.smileidentity.com/v1/async_business_verification

Synchronous

EnvironmentURL

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

NameTypeRequiredDescription

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:

NameTypeDescriptionReturn 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": "smile@smileidentity.com",
    "status": "ACTIVE"
  },
  "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.

CodeTextDescriptionCategory

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

CodeTextDescriptionCategory

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

Last updated