Verify an identity document

​

Verify an identity document. Currently supports BVN (Nigeria).

Headers
  • Idempotency-Key
    Type: string
    min length:  
    1
    max length:  
    255
    required

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

Body·
required
application/json
  • country
    Type: string
    min length:  
    2
    max length:  
    2
    required

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

  • idNumber
    Type: string
    min length:  
    1
    required

    Identity document number. For BVN: exactly 11 digits.

  • idType
    Type: string
    min length:  
    2
    max length:  
    30
    required

    Identity document type. For NG: bvn.

  • mode
    Type: stringenum

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

    values
    • sync
    • async
  • validation
    Type: object

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

Responses
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for post/verify/identity
curl https://api.lira.com/api/v1/verify/identity \
  --request POST \
  --header 'Idempotency-Key: verify-request-20260504-001' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_SECRET_TOKEN' \
  --data '{
  "country": "NG",
  "idType": "bvn",
  "idNumber": "12345678901",
  "mode": "sync",
  "validation": {
    "firstName": "Jane",
    "lastName": "Doe",
    "dateOfBirth": "1990-03-15",
    "selfie": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD/..."
  }
}'

{
  "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"
  }
}

Identity verification result