identify-africa

TypeScript/JavaScript SDK for the Identify Africa KYC, identity verification, and intelligence API. Provides simple, typed access to 50+ verification endpoints spanning identity, business, financial, asset, intelligence, screening, biometric, unified/batch, and regional (Uganda, Zambia, Nigeria, Ghana) services.

Installation

npm install identify-africa

Usage

import { IdentifyAfricaClient, verifyNationalId } from "identify-africa";

const client = new IdentifyAfricaClient({
  apiKey: process.env.API_KEY!,
  apiSecret: process.env.API_SECRET!,
});

const result = await verifyNationalId(client, { idnumber: "12345678" });

if (result.success) {
  console.log(result.data.first_name);
} else {
  console.log(result.message, result.response_code);
}

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

Configuration

| Option | 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 | | timeoutMs | number | No | 10000 | Request timeout in milliseconds | | maxRetries | number | No | 2 | Max retry attempts on transient failures | | retryDelayMs | number | No | 300 | Base delay for exponential backoff | | logger | Logger | No | — | Optional logger (e.g. console) for request/response/retry events |

Store your credentials in your own .env file — never commit them to source control:

API_KEY=your_api_key API_SECRET=your_api_secret

Logging

const client = new IdentifyAfricaClient({
  apiKey: process.env.API_KEY!,
  apiSecret: process.env.API_SECRET!,
  logger: console,
});

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

Available Methods

Every method takes the client as its first argument and a typed params object as its second, and returns Promise<ApiResponse>. Each validates required input client-side before sending the request, throwing a plain Error if validation fails.

Identity Verification

| Method | Endpoint | Params | | -------------------------- | ------------------ | -------------- | | verifyNationalId | /id | { idnumber } | | verifyAlienId | /alienid | { idnumber } | | verifyDrivingLicense | /dl | { idnumber } | | verifyKraPin | /krapin | { idnumber } | | lookupKraByNationalId | /kra-id | { idnumber } | | verifyKenyaPhone | /phone-ke | { number } | | verifyKenyaPhoneExtended | /phone-number-ke | { number } | | lookupSimRegistration | /sim-reg | { number } | | lookupSimDetails | /sim-details | { number } | | getPhoneInfo | /phone-info | { number } |

Business Verification

| Method | Endpoint | Params | | ----------------------- | --------------- | ---------------- | | verifyBusiness | /business | { identifier } | | verifyUbo | /ubos | { identifier } | | verifyBusinessWithUbo | /business-ubo | { identifier } |

Financial Services

| Method | Endpoint | Params | | --------------------------------- | ---------------------------------- | ------------------------ | | verifyBankAccount | /bank | { identifier, bankid } | | getCreditScore | /credit-score | { national_id } | | getMetropolCreditScore | /metropol-credit-score | { national_id } | | getMetropolCreditReport | /metropol-credit-report | { national_id } | | getMetropolCreditReportEnhanced | /metropol-credit-report-enhanced | { national_id } | | checkCollateral | /collateral | { identifier } | | verifyEmployer | /employer-verification | { identifier } | | checkPoliceClearance | /police-clearance | { identifier } |

Asset Verification

| Method | Endpoint | Params | | -------------------- | -------- | ----------- | | verifyVehiclePlate | /plate | { plate } |

Intelligence Services

| Method | Endpoint | Params | | --------------- | -------------- | ---------------- | | getPhoneIntel | /phone-intel | { number } | | getEmailIntel | /email-intel | { email } | | getIpIntel | /ip-intel | { ip_address } | | getDnsIntel | /dns-intel | { domain } |

Advanced Screening

| Method | Endpoint | Params | | ------------------------ | --------------------- | ---------------------------------------- | | checkAml | /aml-check | { first_name, last_name, gender, dob } | | checkAdverseMedia | /adverse-media | { target_name, ... } | | checkSanctions | /sanctions | { q, ... } | | checkCombinedScreening | /combined-screening | { name, ... } | | verifyIndividual | /verify-individual | { first_name, last_name, gender, dob } | | screenBusiness | /screen-business | { business_name, ... } |

Biometric Verification (multipart)

| Method | Endpoint | Params | | ---------------------- | ---------- | ------------------------------ | | checkPassiveLiveness | /gateway | { image } | | compareFaces | /gateway | { sourceImage, targetImage } | | extractDocument | /gateway | { image, documentType } |

Unified & Batch Operations

| Method | Endpoint | Params | | --------------------- | ------------------- | --------------------------------------------------------------------- | | unifiedVerify | /verify | { type, identifier, additional_params? } | | ugandaUnifiedVerify | /verify/ug | { type, identifier } | | compositeVerify | /verify/composite | { verification_path, identifiers } | | batchVerify | /batch-verify | { file, type, selling_price, ... } (multipart) | | startBulkJob | /bulk-jobs | { search_type, selling_price, ... } | | completeBulkJob | /bulk-jobs/{uuid} | { uuid, total_records, successful_records, failed_records } (PATCH) |

Regional Services

| Method | Endpoint | Params | | ------------------------ | -------------- | ------------------ | | verifyUgandaPhone | /ug/phone | { phonenumber } | | verifyUgandaBusiness | /ug/business | { brn } | | verifyZambiaNationalId | /zm/nin | { id_number } | | verifyNigeriaNin | /ng/nin | { number_nin } | | verifyNigeriaBvn | /ng/bvn | { number_bvn } | | verifyNigeriaPhone | /ng/phone | { phone_number } | | verifyGhanaPassport | /gh/passport | { number } | | verifyGhanaTin | /gh/tin | { tin } |

Utility & Gateway

| Method | Endpoint | Params | | ------------- | ----------------- | ----------------------------------- | | getBalance | /balance (GET) | — | | getBankList | /banklist (GET) | — | | healthCheck | / (GET) | — | | callGateway | /gateway | { service, identifier?, params? } |

Response Shape

type ApiResponse<T> = ApiSuccessResponse<T> | ApiErrorResponse;

interface ApiSuccessResponse<T> {
  success: true;
  response_code: number;
  message: string;
  data: T;
  request_id: string;
}

interface ApiErrorResponse {
  success: false;
  response_code: number;
  message: string;
  data: Record<string, unknown> | unknown[];
  request_id: string;
}

Check result.success before accessing result.data — TypeScript will narrow the type accordingly. Most endpoints are typed as Promise<ApiResponse> (untyped data); the original five (verifyNationalId, verifyAlienId, verifyDrivingLicense, verifyVehiclePlate, getPhoneIntel) additionally type data to match their documented success response.

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

npm install
npm run build
npm test

Built with tsup, outputting CJS, ESM, and type declarations to dist/. Tests run with vitest.

Release Process

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

Publishing is currently manual, pending Trusted Publishing (OIDC) setup, which requires 2FA on the npm account:

npm version [patch|minor|major]
git push && git push --tags
npm publish

Pushing a version tag triggers an automated build/test check via GitHub Actions, but does not currently auto-publish.

License

MIT