This document describes the API for fetching details associated with the submitted national ID number.
Base URL
https://identity.cladfy.app/api/v1
API Endpoint:
POST /id
Request Headers:
-
Payload: The data sent to the server in the request body. Here, it's a JSON object with a single key-value pair:
"idnumber": 0
– A placeholder value that should be replaced with an actual ID number. -
Content-Type:
"application/json"
Indicates that the data in the request body is in JSON format. -
Accept:
"application/json"
Tells the server that the client expects the response to be in JSON format. -
Authorization:
"Basic 123"
Used for HTTP Basic Authentication, where"123"
is a placeholder for the base64-encodedusername:password
credentials. See guide here
Request Body:
The request body contains the NationaID number. It should be JSON with the properties below..
idnumber
: The National ID Number -integer
.
Example Request Body:
{
"idnumber": 0
}
Response - 200:
The response will be a JSON object following the request data type specification: A typed dictionary containing the detailed results. Properties include:
-
Success:
boolean
(required)- Indicates the success or failure of the request.
- Example:
true
-
Response Code:
integer
(required)- The HTTP status code of the response.
- Example:
200 (OK)
-
Message:
string
(required)- A human-readable message describing the result of the request.
- Example:
ID Details Fetched Successfully
-
Data:
object
(required)-
Contains the fetched ID details.
-
First Name:
string
(required)- The first name of the individual.
- Example:
JOHN
-
Last Name:
string
(required)- The last name of the individual.
- Example:
DOE
-
Other Name:
string
(required)- Any additional names (middle name, etc.).
- Example:
JOHNNY
-
Name:
string
(required)- The full name of the individual.
- Example:
JOHNNY JOHN SMITH
-
Gender:
string
(required)- The gender of the individual.
- Example:
Male
-
DOB:
string
(required)- The date of birth of the individual in
YYYY-MM-DD
format. - Example:
1995-11-20
- The date of birth of the individual in
-
Citizenship:
string
(required)- The citizenship of the individual.
- Example:
Kenyan
-
ID Number:
string
(required)- The unique identifier for the individual's ID card.
- Example:
123456789
-
Serial No:
string
(required)- The serial number of the ID card.
- Example:
0987654321
-
Valid:
boolean
(required)- Indicates whether the ID card is currently valid.
- Example:
true
-
-
Request ID:
string
(required)- A unique identifier for the request.
- Example:
01000000-0000-0000-0000-000000000001
Example Response:
{
"success": true,
"response_code": 200,
"message": "ID Details Fetched Successfully",
"data": {
"first_name": "JOHN",
"last_name": "DOE",
"other_name": "JOHNNY",
"name": "JOHNNY JOHN DOE",
"gender": "Male",
"dob": "1995-11-20",
"citizenship": "Kenyan",
"id_number": "123456789",
"serial_no": "0987654321",
"valid": true
},
"request_id": "01000000-0000-0000-0000-000000000001"
}
Error Handling:
401 Unauthorized: If the API key is invalid.
400 Bad Request: If the request body is not valid JSON or missing required fields.
500 Internal Server Error: If an internal server error occurs during API request processing. The response will include an error message.
Python Test Example:
This test example demonstrates sending a POST request to the API endpoint with the ID. The response will include the associated details.
import requests
url = "https://identity.cladfy.app/api/v1/id"
payload = { "idnumber": 0 }
headers = {
"Content-Type": "application/json",
"Accept": "application/json",
"Authorization": "Basic 123"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())