identify-africa

Python SDK for the Identify Africa KYC and identity verification API. Provides typed, validated access to national ID, alien ID, driving license, vehicle plate, and phone intelligence verification.

Installation

pip install identify-africa

Usage

from identify_africa import IdentifyAfricaClient, verify_national_id, NationalIdRequest

client = IdentifyAfricaClient(
    api_key="your_api_key",
    api_secret="your_api_secret",
)

result = verify_national_id(client, NationalIdRequest(idnumber="12345678"))

if result["success"]:
    print(result["data"]["first_name"])
else:
    print(result["message"], result["response_code"])

Responses are returned exactly as sent by the API, unmodified — including both success and error payloads.

Configuration

Parameter	Type	Required	Default	Description
api_key	str	Yes	—	Your API key
api_secret	str	Yes	—	Your API secret
environment	"sandbox" | "production"	No	"sandbox"	Which base URL to target
timeout	float	No	10.0	Request timeout in seconds
max_retries	int	No	2	Max retry attempts on transient failures
retry_delay	float	No	0.3	Base delay (seconds) for exponential backoff
logger	Logger	No	—	Optional logger for request/response/retry events

Store your credentials in your own .env file (loaded with a tool like python-dotenv) — never commit them to source control:

API_KEY=your_api_key API_SECRET=your_api_secret

Logging

import logging
from identify_africa import IdentifyAfricaClient

logger = logging.getLogger("identify_africa")
logging.basicConfig(level=logging.DEBUG)

client = IdentifyAfricaClient(
    api_key="...",
    api_secret="...",
    logger=logger,
)

Sensitive request fields (idnumber, plate, number) are automatically masked in log output (e.g. ****5678). Response data is never logged.

Available Functions

verify_national_id(client, NationalIdRequest(idnumber=...))

Verifies a Kenyan National ID number (8 digits).

verify_alien_id(client, AlienIdRequest(idnumber=...))

Verifies an Alien ID number for non-citizens.

verify_driving_license(client, DrivingLicenseRequest(idnumber=...))

Looks up driving license details using a National ID number.

verify_vehicle_plate(client, VehiclePlateRequest(plate=...))

Verifies vehicle registration details using a number plate.

get_phone_intel(client, PhoneIntelRequest(number=...))

Retrieves phone intelligence — carrier, spam score, location, and validation details.

Each function validates required input client-side before sending the request, raising a ValueError if validation fails (some fields are also validated at construction time by the underlying pydantic request models).

Response Shape

Every function returns a plain dict matching the API's response envelope:

{
    "success": bool,
    "response_code": int,
    "message": str,
    "data": ...,        # shape depends on endpoint and success/failure
    "request_id": str,
}

Check result["success"] before relying on result["data"]'s shape.

Error Codes

Code	Meaning	Retried automatically?
200	Success	—
401	Unauthorized — invalid or missing credentials	No
402	Low credit balance	No
412	Validation error (check data for field errors)	No
424	Upstream dependency failure	Yes
502	Upstream service unavailable	Yes

Development

pip install -e ".[dev]"
pytest
python -m build

Built with httpx and pydantic. Tests run with pytest.

Release Process

This project follows Semantic Versioning. CI runs tests and a build check on every push/PR to main.

Publishing to PyPI is automated via Trusted Publishing (OIDC) — pushing a version tag triggers the publish.yml workflow, which runs tests, builds, and publishes with no stored credentials:

# bump version in pyproject.toml
git add .
git commit -m "Release vX.Y.Z"
git tag vX.Y.Z
git push && git push --tags

License

MIT

identify-africa

Python SDK for the Identify Africa KYC and identity verification API. Provides typed, validated access to national ID, alien ID, driving license, vehicle plate, and phone intelligence verification.

Installation

pip install identify-africa

Usage

from identify_africa import IdentifyAfricaClient, verify_national_id, NationalIdRequest

client = IdentifyAfricaClient(
    api_key="your_api_key",
    api_secret="your_api_secret",
)

result = verify_national_id(client, NationalIdRequest(idnumber="12345678"))

if result["success"]:
    print(result["data"]["first_name"])
else:
    print(result["message"], result["response_code"])

Responses are returned exactly as sent by the API, unmodified — including both success and error payloads.

Configuration

Parameter	Type	Required	Default	Description
api_key	str	Yes	—	Your API key
api_secret	str	Yes	—	Your API secret
environment	"sandbox" | "production"	No	"sandbox"	Which base URL to target
timeout	float	No	10.0	Request timeout in seconds
max_retries	int	No	2	Max retry attempts on transient failures
retry_delay	float	No	0.3	Base delay (seconds) for exponential backoff
logger	Logger	No	—	Optional logger for request/response/retry events

Store your credentials in your own .env file (loaded with a tool like python-dotenv) — never commit them to source control:

API_KEY=your_api_key API_SECRET=your_api_secret

Logging

import logging
from identify_africa import IdentifyAfricaClient

logger = logging.getLogger("identify_africa")
logging.basicConfig(level=logging.DEBUG)

client = IdentifyAfricaClient(
    api_key="...",
    api_secret="...",
    logger=logger,
)

Sensitive request fields (idnumber, plate, number) are automatically masked in log output (e.g. ****5678). Response data is never logged.

Available Functions

verify_national_id(client, NationalIdRequest(idnumber=...))

Verifies a Kenyan National ID number (8 digits).

verify_alien_id(client, AlienIdRequest(idnumber=...))

Verifies an Alien ID number for non-citizens.

verify_driving_license(client, DrivingLicenseRequest(idnumber=...))

Looks up driving license details using a National ID number.

verify_vehicle_plate(client, VehiclePlateRequest(plate=...))

Verifies vehicle registration details using a number plate.

get_phone_intel(client, PhoneIntelRequest(number=...))

Retrieves phone intelligence — carrier, spam score, location, and validation details.

Each function validates required input client-side before sending the request, raising a ValueError if validation fails (some fields are also validated at construction time by the underlying pydantic request models).

Response Shape

Every function returns a plain dict matching the API's response envelope:

{
    "success": bool,
    "response_code": int,
    "message": str,
    "data": ...,        # shape depends on endpoint and success/failure
    "request_id": str,
}

Check result["success"] before relying on result["data"]'s shape.

Error Codes

Code	Meaning	Retried automatically?
200	Success	—
401	Unauthorized — invalid or missing credentials	No
402	Low credit balance	No
412	Validation error (check data for field errors)	No
424	Upstream dependency failure	Yes
502	Upstream service unavailable	Yes

Development

pip install -e ".[dev]"
pytest
python -m build

Built with httpx and pydantic. Tests run with pytest.

Release Process

This project follows Semantic Versioning. CI runs tests and a build check on every push/PR to main.

Publishing to PyPI is automated via Trusted Publishing (OIDC) — pushing a version tag triggers the publish.yml workflow, which runs tests, builds, and publishes with no stored credentials:

# bump version in pyproject.toml
git add .
git commit -m "Release vX.Y.Z"
git tag vX.Y.Z
git push && git push --tags

License

MIT