Changelog

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

2026-03-09

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 provider data 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 provider queries are made and no charges are incurred.
Supported countries: Nigeria (NG) for bank account verification.