Face match lookup

POST/v1/nin/face-match/lookup

Authorization

api-key

x-api-key<token>

In: header

Header Parameters

Idempotency-Key?string

Optional. Unique key identifying this request attempt for idempotency.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

nin*string

National Identification Number (NIN). Exactly 11 digits; surrounding or embedded whitespace is stripped before validation. A value that fails validation is rejected with a 400 and is not billed.

Length11 <= length <= 11

enterpriseId*string

The NIMC enterprise key this lookup runs under. Required — NIMC bills the key, so there is no platform fallback (ADR-059).

Match^[A-Za-z0-9_-]+$

Lengthlength <= 64

requestReason*string

Reason for the request

livelinessImages*array<>

Array of liveliness images for face matching

Items1 <= items <= 10

selfieImage*

Selfie image for face matching

provisionalId*string

Your own reference for what this check is for. Required by the register, despite reading like metadata: the session verification-report call rejects the request without it.

provisionalIdName*string

A label for provisionalId. Required by the register — see the note there.

Response Body

`application/json`

curl -X POST "https://example.com/v1/nin/face-match/lookup" \  -H "Content-Type: application/json" \  -d '{    "nin": "11111111111",    "enterpriseId": "ENT1A2B3C4D5E6F",    "requestReason": "creditBackgroundCheck",    "livelinessImages": [      {        "image": "/9j/4AAQSkZJRgABAgAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRof"      }    ],    "selfieImage": {      "image": "--imagebase64--"    },    "provisionalId": "LOAN12345678",    "provisionalIdName": "Loan Facility"  }'

{  "success": true,  "statusCode": 200,  "message": "Request processed successfully",  "timestamp": "2025-10-20T16:30:00.000Z",  "path": "/v1/auth/register",  "data": {    "biographicData": {      "firstName": "TONYE",      "middleName": "AMADA",      "lastName": "AYAFA",      "gender": "m",      "dateOfBirth": "21-12-2000",      "residenceAddressLine1": "6 FEYI ROWLAND CLOSE OKE IRA BADORE LEKKI AJAH",      "residenceAddressLine2": ""    },    "contactData": {      "phone1": "09059432779"    },    "biometricData": [      {        "biometricType": "photo",        "biometricSubType": "face",        "image": "/9j/4AAQSkZJRgABAgAAAQABAAD...",        "imageRef": "",        "compression": "",        "metadata": "",        "quality": 0,        "qualityFormat": ""      }    ],    "sessionData": {      "status": 200,      "success": true,      "message": "User verification process completed",      "data": {        "requestId": "MUSB0639DEB8",        "sessionId": "9631ac7e-20e5-41e5-bb2b-a42f72e6e250",        "faceAuthStatus": "Approved",        "statusReason": "Match",        "facialMatchingScore": "81"      }    },    "requestId": "HHBD35A2CF29",    "status": 0,    "verificationId": {},    "charged": 0  }}