Business Verification

This endpoint allows you to verify a business.

POST {{BASE_URL}}/api/v1/business/verification

Headers

Name	Type	Description
Authentication*	String	Authentication token to track who is making the requests.

Request Body

Name	Type	Description
registration_no*	String	Business registration number to verify

Request Example

{
    "registration_no": "PVT-GYUPEKK"
}

200: Response Example

200: OK

{
    "status": 200,
    "message": "Business verification data fetched successfully",
    "data": {
        "id": 26,
        "verified": "true",
        "status": "registered",
        "registrationDate": "9 April 1998",
        "registrationNo": "PVT-FYUVQBQR",
        "businessName": "Sodapop Inc",
        "branch": null,
        "partners": "[
            {"type":"director_shareholder","name":"JANE DOE","idType":"citizen","idNumber":"67983412","shares":[{"shareCount":"100","nominalValue":null,"name":"ORDINARY"}]},
            {"type":"director_shareholder","name":"JOHN DOE","idType":"citizen","idNumber":"78653421","shares":[{"shareCount":"850","nominalValue":null,"name":"ORDINARY"}]},
            {"type":"director_shareholder","name":"kenya impact incubator limited","idType":"local_company","idNumber":"CPR/2015/652153","shares":[{"shareCount":"50","nominalValue":null,"name":"ORDINARY"}]}]",
        "email": "[email protected]",
        "phoneNumber": "[phone]",
        "postalAddress": "P O BOX 68999 - 00622",
        "physicalAddress": "Sodapop Plaza/Land Reference Number: 1/13413/Kamburu Drive , Kindaruma Road, Fl: 5, Room/Door:  502, LR NO 312/17830 HSE NO 6 THOGOTO ROAD NAIROBI",
        "shareCapital": "[{"shareCount":1000,"nominalValue":1000.0,"name":"ORDINARY"}]",
        "encumbrances": "[]"
    }
}

202: Response Example

In this case, please use the Fetch Results endpoint to retrieve results.

202: PENDING

{
    "status": 202,
    "message": "Search in progress. Please try again later",
    "data": {
        "batch_id": "afd91316-4132-4814-b494-b9361c8513r7"
    }
}

Response Codes

Code	Meaning
200 OK	Successfully verified the identity.
400 Bad Request	Invalid request parameters.
401 Unauthorized	Invalid or missing authentication credentials.
403 Forbidden	Unauthorized
404 Not Found	No data found for the requested identifier.
500 Internal Server Error	An error occurred on the server side.
503 Service Unavailable	BRS systems are down.
202 Process is pending	Could not get result now. Try again later.
429 Rate Limit Exceeded	Rate Limit exceeded
409 Conflict	Request ongoing

Error Handling

Errors are returned in the following format:

{ 
    "status": "error code",   
    "message": "error message" 
}

Common HTTP Status Codes

Code	Message
400 Bad Request	The request was invalid or missing required parameters.
401 Unauthorized	Authentication failed or the token is missing.
403 Forbidden	Access to the resource is denied.
404 Not Found	The requested resource could not be found.
500 Internal Server Error	An error occurred on the server side.
503 Service Unavailable	BRS systems are down.
429 Rate Limit Exceeded	Rate Limit exceeded
409 Conflict	Request ongoing

Error Responses

Bad Request (400)

{   
    "status": 400,   
    "message": "Bad request" 
}

Unauthenticated (401)

{   
    "status": 401,   
    "message": "Unauthenticated" 
}

Unauthorized (403)

{   
    "status": 403,   
    "message": "Insufficient wallet balance" 
}

Not Found (404)

{   
    "status": 404,   
    "message": "No data found for this business identifier" 
}

Internal Server Error (500)

{    
    "status": 500,    
    "message": "Internal server error: Contact [email protected]" 
}

Service Unavailable (503)

{
    "status": 503,    
    "message": "BRS systems are experiencing a downtime." 
}

Conflict

{
    "status": 409,    
    "message": "Request ongoing for this registration number." 
}

Rate Limiting

To ensure fair usage, API requests are subject to rate limits. Exceeding these limits will result in a 429 Too Many Requests response. The current setting prevents duplicate requests within a 2-minute window.

{
   "status": 429,
   "message": "Too many requests: Please wait before retrying."
}