Fetch Results (Optional)

This endpoint allows you to retrieve business verification data for pending searches cases: Cases where the verification endpoint returned 202.

POST {{BASE_URL}}/api/v1/business/results?batch_id=batchId

Request Params

Name	Type	Description
batch_id*	String	batch id returned in the verification endpoint

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

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

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."
}