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-encoded username: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
    • 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())