Verifications

Verify an identity document

post/verify/identity

Verify an identity document. Supports BVN (NG), NIN (TZ), and Ghana Card / Voter ID / Passport (GH).

Authorization

API key in the X-API-Key header.

Headers

Idempotency-Keystringrequired

Required for verification mutations. Use a unique printable ASCII key per logical request; retries with the same key return the original response.

Body required

countrystringrequired

ISO 3166-1 alpha-2 country code. Currently supported: NG, TZ, GH.

idTypestringrequired

Identity document type. NG: `bvn`. TZ: `nin`. GH: `ghana_card`, `voter_id`, `passport`.

idNumberstringrequired

Identity document number. For BVN: exactly 11 digits.

modestring

`sync` returns the verification result in the response. `async` returns `pending` and delivers the final result via your registered webhooks (configure under `/webhooks`).

Options: syncasync

validationobject

Optional fields to cross-check against the registry response. When provided, the verification fails if values do not match.

Show child attributes

firstNamestring

lastNamestring

dateOfBirthstring

Format YYYY-MM-DD

selfiestring

Base64-encoded selfie image for biometric match (data URI or raw base64)

motherFirstNamestring

placeOfBirthstring

sexstring

curl -X POST 'https://api.lira.com/api/v1/verify/identity' \ -H 'X-API-Key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "country": "NG", "idType": "bvn", "idNumber": "12345678901", "mode": "sync", "validation": { "firstName": "Jane", "lastName": "Doe", "dateOfBirth": "1990-03-15", "selfie": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD/...", "motherFirstName": "string", "placeOfBirth": "string", "sex": "string" } }'

import requests response = requests.post( "https://api.lira.com/api/v1/verify/identity", headers={"X-API-Key": "YOUR_API_KEY"}, json={ "country": "NG", "idType": "bvn", "idNumber": "12345678901", "mode": "sync", "validation": { "firstName": "Jane", "lastName": "Doe", "dateOfBirth": "1990-03-15", "selfie": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD/...", "motherFirstName": "string", "placeOfBirth": "string", "sex": "string" } }, ) data = response.json()

{ "id": "c3d4e5f6-a7b8-9012-cdef-345678901234", "status": "success", "verificationType": "BVN", "idType": "bvn", "country": "NG", "identifier": "12345678901", "verifiedAt": "2026-04-22T10:15:30.000Z", "verified": true, "origin": "api", "firstName": "Jane", "lastName": "Doe", "middleName": "Adaeze", "dateOfBirth": "1990-03-15", "phoneNumber": "08012345678", "gender": "Female", "nin": "23456789012", "enrollmentBranch": "Lagos Mainland", "enrollmentInstitution": "Access Bank", "registrationDate": "2015-08-10", "levelOfAccount": "Level 2", "address": { "town": "Ikeja", "lga": "Ikeja", "state": "Lagos", "street": "15 Allen Avenue" }, "error": { "code": "IDENTITY_NOT_FOUND", "message": "BVN not found in the registry" } }

{ "message": "NG Account Number verification is not enabled for your organisation.", "code": "SERVICE_NOT_ENABLED", "action": { "type": "CONTACT_ADMIN", "hint": "Ask your administrator to enable NG Account Number verification in the Lira dashboard." } }