Identity Verification (KYC)

What is KYC and Why Does it Matter?

KYC stands for Know Your Customer. Before you allow anyone to move money through your application, Nigerian law requires you to verify that they are who they claim to be. This isn’t just a technical requirement. It protects you, your customers, and the financial system from fraud, money laundering, and identity theft. The Central Bank of Nigeria (CBN) KYC regulations apply to every financial service that processes payments on behalf of customers. We give you APIs to complete these checks instantly, without your customers having to visit a branch or scan physical documents.

Run KYC before you credit or debit a customer’s account for the first time. Build verification into your onboarding flow, not as an afterthought.

Three Types of Verification

BVN Lookup

Bank Verification Number. An 11-digit number issued by the CBN that links a Nigerian individual to all their registered bank accounts. The most widely used identity check in Nigerian fintech.

NIN Lookup

National Identification Number. An 11-digit number issued by NIMC (National Identity Management Commission). Tied to the National Identity Card and the biometric database.

CAC Lookup

Corporate Affairs Commission. Verify that a business is legitimately registered in Nigeria. Use this when onboarding business customers, merchants, or vendors.

Privacy by Design

We’re deliberate about what data we return, and what we don’t. We never return:

Full BVN or NIN digits
Full date of birth
Biometric data

We return instead:

Masked BVN/NIN (e.g. *****6789)
A name match confidence score (0.0 to 1.0)
Basic demographic signals (e.g. whether the date of birth year matches)

This approach is designed for NDPR compliance (Nigeria Data Protection Regulation). We never store full PII on our servers after the check completes. Your system receives only what’s necessary to make a pass/fail decision.

Understanding the Name Match Score

Every BVN and NIN lookup returns a nameMatchScore: a number between 0 and 1.

Score	Meaning
`0.95` to `1.00`	Very high confidence. Names match closely
`0.80` to `0.94`	Good match. Minor variation (e.g. middle name omitted, shortened first name)
`0.60` to `0.79`	Partial match. Review manually before proceeding
`0.00` to `0.59`	Low confidence. Likely a mismatch. Reject

Reject any verification with a nameMatchScore below 0.80. For scores between 0.60 and 0.79, ask the customer to submit a government-issued ID for manual review instead of outright rejecting them.

BVN Verification

Use BVN as your primary identity check for individual customers.

cURL
JavaScript (fetch)

curl -X POST https://api-partner.onecluster.co/api/v1/kyc/bvn \
  -H "Authorization: ApiKey ubn_sb_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "bvn": "12345678901",
    "firstName": "Adebayo",
    "lastName": "Johnson",
    "dateOfBirth": "1990-06-15"
  }'

const response = await fetch('https://api-partner.onecluster.co/api/v1/kyc/bvn', {
  method: 'POST',
  headers: {
    'Authorization': 'ApiKey ubn_sb_your_key_here',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    bvn: '12345678901',
    firstName: 'Adebayo',
    lastName: 'Johnson',
    dateOfBirth: '1990-06-15',
  }),
});

const result = await response.json();

if (result.data.nameMatchScore >= 0.80) {
  // Proceed with onboarding
} else {
  // Reject or request manual review
}

Response:

{
  "status": "success",
  "data": {
    "verified": true,
    "maskedBvn": "*****78901",
    "nameMatchScore": 0.97,
    "dateOfBirthMatch": true,
    "verificationRef": "KYC-BVN-20260325-001"
  }
}

NIN Verification

Use NIN as a secondary check alongside BVN, or as the primary check when BVN is unavailable (e.g. for customers who are new to banking).

cURL
JavaScript (fetch)

curl -X POST https://api-partner.onecluster.co/api/v1/kyc/nin \
  -H "Authorization: ApiKey ubn_sb_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "nin": "98765432101",
    "firstName": "Adebayo",
    "lastName": "Johnson",
    "dateOfBirth": "1990-06-15"
  }'

const response = await fetch('https://api-partner.onecluster.co/api/v1/kyc/nin', {
  method: 'POST',
  headers: {
    'Authorization': 'ApiKey ubn_sb_your_key_here',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    nin: '98765432101',
    firstName: 'Adebayo',
    lastName: 'Johnson',
    dateOfBirth: '1990-06-15',
  }),
});

const result = await response.json();

Response:

{
  "status": "success",
  "data": {
    "verified": true,
    "maskedNin": "*****32101",
    "nameMatchScore": 0.94,
    "dateOfBirthMatch": true,
    "verificationRef": "KYC-NIN-20260325-001"
  }
}

CAC Lookup (Business Verification)

When onboarding a business customer, use CAC lookup to confirm the company is registered with the Corporate Affairs Commission and retrieve its registered details.

cURL
JavaScript (fetch)

curl -X POST https://api-partner.onecluster.co/api/v1/kyc/cac \
  -H "Authorization: ApiKey ubn_sb_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "rcNumber": "RC1234567",
    "companyName": "Acme Technologies Limited"
  }'

const response = await fetch('https://api-partner.onecluster.co/api/v1/kyc/cac', {
  method: 'POST',
  headers: {
    'Authorization': 'ApiKey ubn_sb_your_key_here',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    rcNumber: 'RC1234567',
    companyName: 'Acme Technologies Limited',
  }),
});

const result = await response.json();

Response:

{
  "status": "success",
  "data": {
    "verified": true,
    "rcNumber": "RC1234567",
    "registeredName": "ACME TECHNOLOGIES LIMITED",
    "nameMatchScore": 0.98,
    "status": "ACTIVE",
    "registrationDate": "2018-04-10",
    "companyType": "Private Limited Company",
    "verificationRef": "KYC-CAC-20260325-001"
  }
}

When to Use Each Check

Scenario	Recommended check
Individual customer signing up	BVN (primary)
Individual with no BVN yet	NIN (primary)
High-risk transaction above a threshold	BVN + NIN (both)
Business / merchant onboarding	CAC lookup + director BVN
Repeat customer with existing verification	Skip. Store `verificationRef`. Don’t re-check

Store the verificationRef returned from each successful check. If a customer has already been verified, you don’t need to call the API again. Re-checking costs API quota and adds latency for the customer.

Handling Verification Results

Match (nameMatchScore >= 0.80)

The identity check passed. Store the verificationRef against the customer record and proceed with onboarding. You don’t need to store any PII from the check. The ref is your audit trail.

Partial Match (nameMatchScore 0.60 to 0.79)

The names are similar but not a strong match. Common causes: the customer’s registered bank name uses a different format (e.g. initials instead of full name), or a middle name is included in one record but not the other.Recommended approach: Don’t auto-approve. Ask the customer to upload a government-issued ID for manual review, or ask them to confirm their name exactly as it appears on their BVN/NIN record.

No Match (nameMatchScore < 0.60)

The names don’t match. Either the wrong BVN/NIN was entered, or the customer’s identity information doesn’t match.Recommended approach: Reject the verification attempt. Let the customer re-enter their BVN/NIN in case of a typo. Log the attempt for fraud monitoring.

Check Failed (API error)

The verification service couldn’t be reached, or the BVN/NIN was not found in the registry. This is different from a no-match. It means the check couldn’t be completed.Recommended approach: Retry once after a short delay. If it fails again, surface a friendly error to the customer and let them try again later. Don’t block the customer permanently for a transient API failure.HTTP 422 means the BVN/NIN format is invalid (check the length and that it contains only digits). HTTP 404 means the BVN/NIN wasn’t found in the registry.

Rate Limits

Endpoint	Limit
`POST /api/v1/kyc/bvn`	100 requests per hour per API key
`POST /api/v1/kyc/nin`	100 requests per hour per API key
`POST /api/v1/kyc/cac`	200 requests per hour per API key

If you expect higher volumes (e.g. a large onboarding campaign), contact baas-support@unionbank.ng in advance to have your limits reviewed.

Rate limits apply per API key, not per customer. If you’re running a high-volume batch verification (e.g. verifying an existing customer base), spread requests over time or request a temporary limit increase.

Getting Started

Onboarding

Products

Security & Compliance

Resources

Identity Verification (KYC)

What is KYC and Why Does it Matter?

Three Types of Verification

BVN Lookup

NIN Lookup

CAC Lookup

Privacy by Design

Understanding the Name Match Score

BVN Verification

NIN Verification

CAC Lookup (Business Verification)

When to Use Each Check

Handling Verification Results

Rate Limits

​What is KYC and Why Does it Matter?

​Three Types of Verification

BVN Lookup

NIN Lookup

CAC Lookup

​Privacy by Design

​Understanding the Name Match Score

​BVN Verification

​NIN Verification

​CAC Lookup (Business Verification)

​When to Use Each Check

​Handling Verification Results

​Rate Limits

What is KYC and Why Does it Matter?

Three Types of Verification

Privacy by Design

Understanding the Name Match Score

BVN Verification

NIN Verification

CAC Lookup (Business Verification)

When to Use Each Check

Handling Verification Results

Rate Limits