National ID

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:

JSON

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

JSON

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

Python

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())