identify-africa / sdk

v1.2.0 2026-08-31 11:23 UTC

Requires

• php: >=8.1
• guzzlehttp/guzzle: ^7.0
• psr/log: ^3.0

Requires (Dev)

• phpunit/phpunit: ^10.0

MIT

• magwach

Published on Packagist.org on 2026-08-31 11:24 UTC

README

PHP 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

composer require identify-africa/sdk

Usage

<?php

require 'vendor/autoload.php';

use IdentifyAfrica\Client;
use IdentifyAfrica\Endpoints\NationalId;
use IdentifyAfrica\Models\NationalId\NationalIdRequest;

$client = new Client(
    apiKey: getenv('API_KEY'),
    apiSecret: getenv('API_SECRET')
);

$result = NationalId::verify($client, new NationalIdRequest(idnumber: '12345678'));

if ($result['success']) {
    echo $result['data']['first_name'] . PHP_EOL;
} else {
    echo $result['message'] . PHP_EOL;
}

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

Configuration

Parameter	Type	Required	Default	Description
apiKey	string	Yes	—	Your API key
apiSecret	string	Yes	—	Your API secret
environment	'sandbox' | 'production'	No	'sandbox'	Which base URL to target
timeout	float	No	10.0	Request timeout in seconds
maxRetries	int	No	2	Max retry attempts on transient failures
retryDelay	float	No	0.3	Base delay (seconds) for exponential backoff
logger	Psr\Log\LoggerInterface	No	—	Optional PSR-3 logger for request/response/retry events

Store your credentials in your own .env file (loaded with a library like vlucas/phpdotenv) — never commit them to source control:

API_KEY=your_api_key API_SECRET=your_api_secret

Logging

Accepts any PSR-3 compatible logger, such as Monolog:

use Monolog\Logger;
use Monolog\Handler\StreamHandler;

$logger = new Logger('identify-africa');
$logger->pushHandler(new StreamHandler('php://stdout'));

$client = new Client(
    apiKey: getenv('API_KEY'),
    apiSecret: getenv('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 Methods

NationalId::verify($client, new NationalIdRequest(idnumber: ...))

Verifies a Kenyan National ID number (8 digits).

AlienId::verify($client, new AlienIdRequest(idnumber: ...))

Verifies an Alien ID number for non-citizens.

DrivingLicense::verify($client, new DrivingLicenseRequest(idnumber: ...))

Looks up driving license details using a National ID number.

VehiclePlate::verify($client, new VehiclePlateRequest(plate: ...))

Verifies vehicle registration details using a number plate.

PhoneIntel::get($client, new PhoneIntelRequest(number: ...))

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

Each method validates required input client-side before sending the request, throwing an InvalidArgumentException if validation fails.

Response Shape

Every method returns an associative array matching the API's response envelope:

[
    'success' => bool,
    'response_code' => int,
    'message' => string,
    'data' => ..., // shape depends on endpoint and success/failure
    'request_id' => string,
]

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

composer install
composer test

Built with Guzzle for HTTP and PSR-3 for logging. Tests run with PHPUnit, across PHP 8.1–8.3 in CI.

Release Process

This project follows Semantic Versioning. CI runs the full test suite on every push/PR to main.

Publishing is handled by Packagist, which reads directly from this repository's git tags — there is no separate build/upload step:

git add .
git commit -m "Release vX.Y.Z"
git tag vX.Y.Z
git push && git push --tags

Packagist picks up new tags automatically via webhook shortly after pushing.

License

MIT