> For the complete documentation index, see [llms.txt](https://legacy-docs.usesmileid.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://legacy-docs.usesmileid.com/products/for-businesses-kyb/business-verification.md). # Business Verification Product {% hint style="info" %} For the list of supported countries and search types, please check [this section](/supported-id-types/for-individuals-kyc/backed-by-id-authority/supported-countries.md) of the documentation. {% endhint %} ## 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, trustees, and fiduciaries of a business while the tax information returns only the company information. ## Integration Options Only available using [Rest API](/integration-options/rest-api.md)s. ## 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](/further-reading/faqs/how-do-i-setup-a-callback.md) in your request where the response will be delivered. The urls for the endpoints are: #### Asynchronous | Environment | URL | | ----------- | ---------------------------------------------------------------------- | | Sandbox: | | | Production: | | #### Synchronous | Environment | URL | | ----------- | -------------------------------------------------------------- | | Sandbox: | | | Production: | | ### Request Values The Business Verification 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](https://portal.usesmileid.com/api-key) | | 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](/further-reading/faqs/how-do-i-setup-a-callback.md) | | country | string | Yes | The country where the business is incorporated. Link to country codes [here](/supported-id-types/for-businesses-kyb/id-number-regex.md). | | id\_type | string | Yes | The search type you want to query. `BUSINESS_REGISTRATION` or`TAX_INFORMATION` or `BASIC_BUSINESS_REGISTRATION` | | id\_number | string | Yes | The business registration number (for Business\_Registration or Basic\_Business\_Registration) 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 ```json { "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](#_bppecaxtpz6v). | | ResultCode | string | Numeric value of the job outcome | For a list of potential result codes see [here](#_bppecaxtpz6v). | | 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 | | | **trustees** | array | A JSON array of objects containing information about the trustees associated with the business. | | | name | string | The full name of the trustee | | | trustee\_type | string | The type of trustee | | | address | string | The address of the trustee filed at the registration agency | | | gender | string | The gender of the trustee | | | phone\_number | string | The phone number of the trustee | | | registration\_number | string | The registration number of trustee. Only returned if the trustee is an organization. | | | nationality | string | The nationality of the trustee | | | occupation | string | The role of the trustee in the company | | | is\_chairman | boolean | If the person is the chairman of the incorporated trustees | | | email | string | The email address of the trustee | | | date\_of\_birth | string | The date of birth of the trustee | | | date\_of\_appointment | string | The date trustee was of appointed | | | **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 ```json { "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": "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](/supported-id-types/for-individuals-kyc/backed-by-id-authority/supported-countries.md) 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](/supported-id-types/for-individuals-kyc/backed-by-id-authority/supported-countries.md) for this search type. | | | 2220 | Error - Production is not enabled for this account. Please [complete your KYC](/getting-started/complete-your-kyc.md). | 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)
|
  • 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](/further-reading/troubleshooting/troubleshooting-error-2204-and-2205-youre-not-authorized-to-do-that.md) ### 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 | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://legacy-docs.usesmileid.com/products/for-businesses-kyb/business-verification.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.