Fetch Verification

Fetch Verification (Sync)

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

This endpoint allows you to verify a customer details synchronously.

Headers

Name	Type	Description
Authentication	string	Authentication token to track down who is emptying our stocks.

Request Body

Name	Type	Description
identifier_type*	String	The identifier type being used for the verification (national_id or passport_no)
identifier*	String	Identifier value
first_name*	String	First name of the individual
last_name*	String	Last name of the individual

200: OK Verification successfully retrieved. (NATIONAL ID)

{
   "status": 200,
   "message": "Verification data fetched successfully",
   "data": {
       "national_id": "550000055",
       "full_name": "Peter Marangi",
       "first_name": "Peter",
       "last_name": "Marangi",
       "surname": null,
       "other_names": null,
       "gender": "M",
       "clan": null,
       "family": null,
       "photo": null,
       "citizenship": null,
       "occupation": null,
       "reg_office": null,
       "ethnic_group": null,
       "date_of_birth": null,
       "date_of_death": null,
       "date_of_issue": null,
       "place_of_live": null,
       "serial_number": null,
       "place_of_birth": null,
       "place_of_death": null
   }
}

JSON Payload - National ID

{ 
 "identifier_type": "national_id", 
 "identifier": "550000055",
 "first_name": "Jane",
 "last_name": "Doe",
}

JSON Payload - Passport

{ 
 "identifier_type": "passport_no", 
 "identifier": "AK078R474",
 "first_name": "Jane",
 "last_name": "Doe",
}

Response Codes

Code	Meaning
200 OK	Successfully verified the identity.
400 Bad Request	Invalid request parameters.
401 Unauthorized	Invalid or missing authentication credentials.
404 Not Found	No data found for the requested identifier.
500 Internal Server Error	An error occurred on the server side.
503 Service Unavailable	IPRS systems are down.

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	IPRS systems are down.

Error Responses

Bad Request (400)

{   
    "status": 400,   
    "message": "identifier_type is required" 
}

{
  "status": 400,
  "message": "Identifier should contain only digits for national_id"
}

{
  "status": 400,
  "message": "Identifier should be between 6 and 10 digits long for national_id"
}

Internal Server Error (500)

{    
    "status": 500,    
    "message": "Internal server error: Contact [e-mail]" 
}

Service Unavailable (503)

{
    "status": 503,    
    "message": "IPRS systems are experiencing a nationwide downtime, and our backup providers have no data for the requested identifier." 
}

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