Changelog

All notable changes to the Lira API are documented here. Breaking changes are marked explicitly. Dates follow ISO 8601 (YYYY-MM-DD).

2026-04-24

Francophone Africa coverage: Bank account and phone number verification now supported for Côte d'Ivoire (CI), Senegal (SN), Cameroon (CM), Burkina Faso (BF), Mali (ML), Benin (BJ), and Togo (TG). Tanzania (TZ) is also added. All phone verifications for the new markets require a networkCode — contact support for the carrier code list per country.

Ghana phone number verification: POST /verify/phone now supports Ghana (GH) in addition to Nigeria. Ghana verifications require a networkCode (MTN, Vodafone, or AirtelTigo). Omitting networkCode for a GH request returns NETWORK_CODE_REQUIRED.
Webhook delivery history: New endpoints to inspect webhook delivery attempts:
- GET /client/webhooks/:id/deliveries: list recent deliveries with status and response details
- GET /client/webhooks/:id/deliveries/:deliveryId: get a specific delivery record
Async verification mode: All verification endpoints now accept "mode": "async". The API returns status: pending immediately and delivers the result via webhook when processing completes.
lastUsedAt on API keys: GET /client/api-keys responses now include a lastUsedAt timestamp showing when each key was most recently used.
expiresAt on API keys: API key list responses include an expiresAt field. Currently null for all keys; expiry configuration will be supported in a future release.

Webhook retry schedule updated: Retry delays changed from fixed 5-minute intervals to exponential backoff: immediate → 1 min → 3 min → 9 min → 27 min. Total retry window is approximately 40 minutes (previously 25 minutes). No action required for existing webhooks.
X-Signature header format: Webhook signature headers now use the sha256=<hex> prefix format. Previously the raw hex digest was sent without a prefix. Update your signature verification logic to strip the sha256= prefix before comparing.

Migration: If you were comparing the header directly against a computed hex digest, update to:
```
const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
```

Resolved an issue where GET /verify with status=pending returned completed verifications in some edge cases.
PATCH /client/webhooks/:id no longer requires all fields to be present; partial updates work as documented.

Webhook management API: New endpoints for registering and managing webhook endpoints:
- POST /client/webhooks: register an endpoint
- GET /client/webhooks: list all webhooks, with optional status and event filters
- GET /client/webhooks/:id: get a single webhook
- PATCH /client/webhooks/:id: update URL, events, status, or signing secret
- DELETE /client/webhooks/:id: delete a webhook
Verification list endpoint: GET /verify returns a paginated list of past verifications. Supports type, status, limit, and offset query parameters.
Verification retrieve endpoint: GET /verify/:id retrieves the result of a specific verification by ID. Useful as a polling fallback when a webhook delivery is missed.

API key header renamed: The authentication header for verification endpoints changed from X-Lira-Key to X-API-Key. The old header will continue to work until 2026-05-15; update before that date to avoid disruption. (Breaking change, grace period active)

Phone number verification: POST /verify/phone verifies that a mobile number is registered with a carrier and returns the subscriber's name and date of birth. Supported country: Nigeria (NG).
DEVELOPER role: New organization role with access to verification endpoints and webhook management. Cannot create or revoke API keys.

Verification response shape: Responses from POST /verify/account now include a top-level verified boolean field (in addition to status) for quick checks. verified: true is equivalent to status: "success".

Bank account verification: POST /verify/account verifies a Nigerian bank account against official records and returns the account holder's name and address.
Authentication: POST /auth/login, POST /auth/refresh, POST /auth/logout for JWT-based session management.
API key management: POST /client/api-keys, GET /client/api-keys, DELETE /client/api-keys/:id for creating and revoking API keys scoped to sandbox or live environments.
Sandbox environment: All endpoints are available in sandbox with deterministic test data. No real external queries are made and no charges are incurred.
Supported countries: Nigeria (NG) for bank account verification.