Validation APIs

The Validation APIs let you confirm a customer’s identity and bank details, so you can automate KYC and filter out fraudulent users before they onboard or transact.

Bank Verification Number (BVN)

The Bank Verification Number (BVN) is Nigeria’s national ID system for uniquely identifying bank customers. Banks maintain a mechanism for retrieving all accounts tied to a given BVN, and these endpoints let you retrieve a customer’s linked accounts, but only after the customer has granted explicit consent.

The flow is two-stage: an initial call starts the process and triggers a One-Time Password (OTP) sent to the customer’s registered phone or email; the customer provides that OTP, and a second call verifies it and returns the account/BVN information.

Initialize BVN consent

Starts the consent process. Pass the customer’s BVN and phone number or email.

curl --location 'https://adjutor.lendsqr.com/v2/verification/bvn/:bvn/accounts' \
--header 'Authorization: Bearer {your_api_key}' \
--data-raw '{
    "contact": "ado****@example.com"
}'

{
  "status": "otp",
  "message": "Please provide OTP sent to contact",
  "data": "0808***2636",
  "meta": {
    "cost": 0,
    "balance": 4815
  }
}

Complete consent and get BVN details

Retrieves the bank accounts linked to a BVN once the customer has supplied the OTP sent to them (SMS OTPs are typically sent from the PFAlert sender ID).

curl --location --request PUT 'https://adjutor.lendsqr.com/v2/verification/bvn/:bvn/accounts' \
--header 'Authorization: Bearer {your_api_key}' \
--data '{
    "otp": "998278"
}'

{
  "status": "success",
  "message": "Successful",
  "data": {
    "reference": 10000001,
    "bvn": "22123456789",
    "first_name": "ADO",
    "middle_name": "JOHN",
    "last_name": "SULE",
    "dob": "1990-10-31",
    "mobile": "08012345678",
    "registration_date": "30-Mar-2015",
    "enrollment_bank": "044",
    "email": "[email protected]",
    "gender": "Male",
    "marital_status": "Single",
    "residential_address": "Ogun State",
    "state_of_origin": "Ogun State",
    "watchlisted": 0,
    "image_url": "https://picsum.photos/id/1/5000/3333"
  },
  "meta": {
    "cost": 20,
    "balance": 4815
  }
}

Known issues

• The OTP may not be delivered to the customer’s phone on time, or at all.
• The OTP may arrive late due to GSM network delays.
• The customer may no longer have access to the phone or email on record, so they may never be able to provide consent.
• The data returned may be incomplete if a bank hasn’t registered all of a customer’s accounts.

BVN image match

Verifies an individual’s BVN in real time by comparing a photograph against the facial features on their BVN record, adding a layer of security to customer validation.

curl --location 'https://adjutor.lendsqr.com/v2/verification/bvn/22536011111/selfies' \
--header 'Authorization: Bearer {your_api_key}' \
--data '{
    "image": "https://documents.lendsqr.com/irorun/45eab612ad3efff8f3da1e65130be8538b8fd6c8602da4252ec35c61ec18802b1619ba7eda625b3efb671bfc478cad84e834c5ad858722e993889b3xxxxxx.png"
}'

{
  "status": "success",
  "message": "Successful",
  "data": {
    "match": true,
    "similarity": 99.94831085205078
  },
  "meta": {
    "cost": 30,
    "balance": 1285
  }
}

The image must be a URL that’s accessible to anyone with the link. You can configure the similarity threshold you’re comfortable accepting in your own application.

Bank account verification

Verifies a customer’s bank account and confirms it’s linked to their BVN, so you can be confident before setting up an account, creating a direct debit mandate, or sending money.

curl --location 'https://adjutor.lendsqr.com/v2/verification/bankaccount/bvn' \
--header 'Authorization: Bearer {your_api_key}' \
--data '{
    "account_number": "0425571111",
    "bank_code": "058"
}'

{
  "status": "success",
  "message": "Successful",
  "data": {
    "bank_code": "058",
    "account_name": "DOE JOHN",
    "account_number": "0425571111",
    "bvn": "22000000021"
  },
  "meta": {
    "cost": 10,
    "balance": 1245
  }
}

Karma lookup

Karma is a database of blacklisted bad actors within the Lendsqr ecosystem: people involved in fraud, who’ve applied for loans under a fake identity, or who are chronic defaulters with a written-off loan. This endpoint checks whether a customer is on that blacklist.

You can look someone up by any of these identifiers:

Field	Format	Example
Email address	[email protected]	[email protected]
Phone number	+234XXXXXXXXXX	+2347012345678
Domain name	example.com	example.com
BVN	11-digit number	22212345678
NUBAN account number	XXX-1234567890, where XXX is the CBN bank code	070-1234567890 for a Fidelity Bank account
Images	Base64	Base64-encoded string

curl --location 'https://adjutor.lendsqr.com/v2/verification/karma/0zspgifzbo.ga' \
--header 'Authorization: Bearer {your_api_key}'

{
  "status": "success",
  "message": "Successful",
  "data": {
    "karma_identity": "0zspgifzbo.ga",
    "amount_in_contention": "0.00",
    "reason": null,
    "default_date": "2020-05-18",
    "karma_type": {
      "karma": "Others"
    },
    "karma_identity_type": {
      "identity_type": "Domain"
    },
    "reporting_entity": {
      "name": "Blinkcash",
      "email": "[email protected]"
    }
  },
  "meta": {
    "cost": 10,
    "balance": 1600
  }
}

It’s up to you whether to proceed with a flagged customer or not.

Ecosystem lookup

The Lendsqr ecosystem aggregates borrower data across our lenders, giving you a broad view of a customer’s credit history and behavior. To use this endpoint you must have the customer’s BVN, and you must have evidence of their explicit consent: where consent wasn’t obtained, you’re liable for any resulting legal costs, and you may be removed from the platform.

curl --location 'https://adjutor.lendsqr.com/v2/verification/ecosystem/22153475955' \
--header 'Authorization: Bearer {your_api_key}'

{
  "status": "success",
  "message": "Successful",
  "data": {
    "bvn": "22536011111",
    "first_name": "JANE",
    "last_name": "DOE",
    "date_of_birth": "1997-09-10T00:00:00.000Z",
    "age": 25,
    "lenders": 1,
    "first_account": "2020-11-16T10:49:57.000Z",
    "last_account": "2023-06-26T07:56:37.000Z",
    "loans": 0,
    "loan_amount_minimum": 0,
    "loan_amount_maximum": 150000,
    "loan_amount_average": 5892.954545,
    "settled_loans": 0,
    "running_loans": 0,
    "past_due_loans": 0,
    "past_due_loan_amount_due": 2000,
    "delayed_paid_loans": 0,
    "logins": 115,
    "first_login": "2023-06-01T12:32:27.000Z",
    "last_login": "2023-08-08T08:23:49.000Z",
    "credit_delinquency": 0,
    "processed_on": "2023-08-08T14:02:33.000Z"
  },
  "meta": {
    "cost": 25,
    "balance": 1590
  }
}

Each field describes an aspect of the customer’s history within the ecosystem. Use it to set up configurations and decide, by your own criteria, whether to proceed with a customer.

Questions about any of these endpoints? Email [email protected].