Global Gateway Modern Rails Single endpoint

Unified Identity Gateway

One endpoint for all sovereign identity databases. Verify a NIN, BVN, or company CAC number by changing a single field — id_type — in your request body. No endpoint switching, no different authentication flows, no SDK juggling.

The level parameter controls data depth: basic for fast identity confirmation, advanced for full profile disclosure including UBO data for companies and biometric photos for individuals. Use the method parameter to enable biometric workflows.

🇳🇬 NIN

National Identity Numbers against the NIMC sovereign database.

🏦 BVN

Bank Verification Numbers against the NIBSS central financial registry.

🏢 CAC

Company registration numbers against the Nigerian CAC registry, including UBO data.

Endpoint

POST /v1/identities/verify/ Requires API key

Request Payload

Send as Content-Type: application/json. All requests must include Authorization: Bearer <api-key>.

Field Description

country string · Required ISO 3166-1 alpha-2 country code. Currently NG (Nigeria) is supported.

id_type

string · Required The identity type to verify. Determines which sovereign database is queried.

Value	Source	Status
NIN	NIMC national identity database	Live
BVN	NIBSS bank verification registry	Live
CAC	Nigerian CAC company registry	Live

method string · Optional · Default: "identity" Verification method. identity returns the identity record. biometric enables biometric photo retrieval on advanced tiers.

level

string · Optional · Default: "basic" Data depth tier.

basic Core identity fields — name, DOB, gender, phone, photo (individuals) or company name, status, directors (companies).

advanced Full profile including residential address, employment, marital status (NIN), UBO data and shareholding (CAC), enrollment details (BVN).

params

object · Required Contains the specific identifier for the selected id_type. The key inside params is always id_number.

id_type	params.id_number example
NIN	"89184072280"
BVN	"22123456789"
CAC	"RC200002"

Response Envelope

All responses share the same top-level structure. The data shape varies by id_type and level.

Field	Type	Description
success	boolean	`true` when verification completed without a server fault. Always check `code` for the outcome.
code	string	Machine-readable result. `NIN_VERIFIED`, `BVN_VERIFIED`, or `CAC_VERIFIED` on success.
message	string	Human-readable status description.
verification_type	string	Echoes the `id_type` from the request (`"NIN"`, `"BVN"`, `"CAC"`).
summary.verified	boolean	Convenience boolean — `true` when the record was found and data returned.
data	object	Identity record from the source database. Shape depends on `id_type` and `level`. See Data Shapes below.
meta.request_id	string	Unique request identifier. Include in all support queries.
meta.timestamp	string	UTC response time in ISO 8601 format.

Data Shapes by id_type

The data object shape varies depending on which sovereign database was queried. Key fields are listed below — see the dedicated endpoint docs for the complete field reference.

🇳🇬 NIN id_type: "NIN"

Full reference →

Key fields returned at basic level: nin, firstname, lastname, gender, birthdate, phone, photo (Base64), residence.

advanced adds: email, profession, marital status, employment, religion, state of origin, next-of-kin, signature, tracking ID.

🏦 BVN id_type: "BVN"

Full reference →

Key fields returned at basic level: bvn, firstname, lastname, birthdate, gender, phone, photo (Base64).

advanced adds: enrollment bank, account details, and full NIBSS profile.

🏢 CAC id_type: "CAC"

Full reference →

Key fields returned at basic level: companyName, rcNumber, status, registrationDate, company type.

advanced adds: affiliatesData (directors and shareholders with shareholding percentages — required for UBO checks).

Error Codes

HTTP	Code	Cause & Resolution
400	INVALID_SCHEMA	`id_type` is unsupported, `params` is missing or malformed, or a required field is absent.
400	VERIFICATION_FAILED	The source database returned an error for the supplied ID. Retry once — if it persists, contact support with the `meta.request_id`.
401	AUTH_FAILURE	Bearer token is missing, malformed, or expired. Regenerate your API key in the Console.
401	UNAPPROVED_ORGANIZATION	Your organisation has not been approved for live access. Complete verification in the Console.
401	SUBSCRIPTION_REQUIRED	The requested `id_type` service is not enabled for your account. Enable it under Services in the Console.
402	INSUFFICIENT_FUNDS	Wallet balance is below the cost of this request. Top up in the Console.
404	RECORD_NOT_FOUND	No matching identity found in the sovereign registry. Verify the `params.id_number` is correct and the `id_type` matches.
503	SERVICE_UNAVAILABLE	Cannot reach the upstream registry. Retry with exponential backoff. Check the status page.
500	SERVER_ERROR	Unexpected internal error. Retry once. If it persists, contact support with the `meta.request_id`.

When to use the Unified Gateway

Use the Unified Gateway when…

Your application verifies more than one ID type (e.g. NIN for individuals, CAC for businesses).
You want a single integration point that doesn't change as you add new ID types.
You need to switch ID types dynamically based on user input without branching your HTTP client code.

Use the dedicated endpoints when…

You only ever verify one ID type and want the simplest possible request body.
You need the full field reference for a specific identity type without the params wrapper.

Select ID type

Example Request

import requests

url = "https://api.lumiid.com/v1/identities/verify/"

payload = {
    "country": "NG",
    "id_type": "NIN",
    "method":  "identity",
    "level":   "basic",
    "params": {
        "id_number": "89184072280"
    }
}

headers = {
    "Authorization": "Bearer Your-Secret-Key",
    "Content-Type":  "application/json"
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()

if not data["success"]:
    print("Error:", data["code"], data["message"])
else:
    print("Verified:", data["summary"]["verified"])
    print("Data:", data["data"])
    print("Req ID:", data["meta"]["request_id"])

const response = await fetch(
  'https://api.lumiid.com/v1/identities/verify/',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer Your-Secret-Key',
      'Content-Type':  'application/json'
    },
    body: JSON.stringify({
      country:  'NG',
      id_type:  'NIN',
      method:   'identity',
      level:    'basic',
      params: {
        id_number: '89184072280'
      }
    })
  }
);

const data = await response.json();

if (!data.success) {
  console.error(`[${data.code}] ${data.message}`);
} else {
  console.log('Verified:', data.summary.verified);
  console.log('Data:', data.data);
  console.log('Req ID:', data.meta.request_id);
}

curl -s -X POST \
  https://api.lumiid.com/v1/identities/verify/ \
  -H "Authorization: Bearer Your-Secret-Key" \
  -H "Content-Type: application/json" \
  -d '{
    "country":  "NG",
    "id_type":  "NIN",
    "method":   "identity",
    "level":    "basic",
    "params":   { "id_number": "89184072280" }
  }'

Sample Response 200 OK

{
  "success": true,
  "code": "NIN_VERIFIED",
  "message": "NIN verification successful",
  "verification_type": "NIN",
  "summary": {
    "verified": true,
    "verification_type": "NIN",
    "provider": "LumiID",
    "confidence_score": 1.0
  },
  "data": {
    "nin": "89184072280",
    "firstname": "TERHEMBA",
    "lastname": "JUDE",
    "gender": "m",
    "birthdate": "06-01-1974",
    "phone": "08000000000",
    "photo": "/9j/4AAQSkZJRgABAgAAAQABAAD...",
    "residence": {
      "state": "FCT Abuja",
      "lga": "Abuja Municipal"
    }
  },
  "meta": {
    "request_id": "req_a3f9c21d9b4e",
    "timestamp": "2026-03-19T09:40:11.445821Z"
  }
}

Record Not Found 404

{
  "success": false,
  "code": "RECORD_NOT_FOUND",
  "message": "No matching identity found in the sovereign registry.",
  "verification_type": "NIN",
  "data": null,
  "meta": {
    "request_id": "req_f7b22e901a33",
    "timestamp": "2026-03-19T09:41:02.119043Z"
  }
}