Phone Number

This document describes the API that returns the details associated with the submitted phone number and institution(Telco), ensuring the accuracy and validity of the information provided.

Base URL

https://identity.cladfy.app/api/v1

API Endpoint:

POST /phone

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:
  "account_number": 0 – A placeholder value that should be replaced with an actual phone number.
  "institution_code": 0 – A placeholder value that should be replaced with an institution code.

• 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 phone number and institution code. It should be JSON with the properties below.

• account_number: A phone number. - string.
• institution_code: A valid institution code. - string. See supported institutions here.

Example Request Body:

JSON

{
  "account_number": "string",
  "institution_code": "string"
}

Response - 200:

The response will be a JSON object following the request data type specification: A typed dictionary containing the detailed results. Properties include:

Response Description

• success

  • Type: boolean
  • Required: Yes

• response_code

  • Type: integer
  • Required: Yes
  • Example: 200

• message

  • Type: string
  • Required: Yes
  • Example: Phone Number Details Fetched Successfully

• data

  • Type: object
  • Required: Yes
  • name
    • Type: string
    • Required: Yes
    • Example: JANE DOE SMITH
  • phone
    • Type: string
    • Required: Yes
    • Example: [phone]
  • institution
    • Type: string
    • Required: Yes
    • Example: Safaricom
  • reference
    • Type: string
    • Required: Yes
    • Example: 79ed217f-9c3b-470b-9a5e-4859e873d005

• request_id

  • Type: string
  • Required: Yes
  • Example: 550e8400-e29b-41d4-a716-446655440000

Example Response:

JSON

{
  "success": true,
  "response_code": 200,
  "message": "Phone Number Details Fetched Successfully",
  "data": {
    "name": "JANE DOE SMITH",
    "phone": "[phone]",
    "institution": "Safaricom",
    "reference": "79ed217f-9c3b-470b-9a5e-4859e873d005"
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

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 Phone Number and Institution Code. The response will include the associated details.

Python

import requests

url = "https://identity.cladfy.app/api/v1/phone"

payload = {
    "account_number": "string",
    "institution_code": "string"
}
headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Authorization": "Basic 123"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())

Supported Institutions

Code	Institution
63902	Safaricom.
Coming Soon	Airtel
Coming Soon	Telkom