Lookup BVN

curl --request GET \
  "https://api.dojah.io/api/v1/kyc/bvn/full?bvn=22222222222" \
  -H "Authorization: {{secret_key}}" \
  -H "AppId: {{app_id}}"

const params = new URLSearchParams({
  "bvn": "22222222222",
});

const url = "https://api.dojah.io/api/v1/kyc/bvn/full?" + params;
const res = await fetch(url, {
  headers: {
    Authorization: process.env.DOJAH_SECRET_KEY,
    AppId: process.env.DOJAH_APP_ID,
  },
});
const data = await res.json();

import os, requests

res = requests.get(
    "https://api.dojah.io/api/v1/kyc/bvn/full",
    headers={
        "Authorization": os.environ["DOJAH_SECRET_KEY"],
        "AppId": os.environ["DOJAH_APP_ID"],
    },
    params={ "bvn": "22222222222" },
)
data = res.json()

{
  "entity": {
    "bvn": "2*****234567",
    "first_name": "JOHN",
    "last_name": "MUSA",
    "middle_name": "DOE",
    "gender": "Male",
    "date_of_birth": "1997-05-16",
    "phone_number1": "08012345678",
    "image": "BASE 64 IMAGE",
    "phone_number2": "08012345678"
  }
}

curl --request GET \
  "https://api.dojah.io/api/v1/kyc/bvn/full?bvn=22222222222" \
  -H "Authorization: {{secret_key}}" \
  -H "AppId: {{app_id}}"

const params = new URLSearchParams({
  "bvn": "22222222222",
});

const url = "https://api.dojah.io/api/v1/kyc/bvn/full?" + params;
const res = await fetch(url, {
  headers: {
    Authorization: process.env.DOJAH_SECRET_KEY,
    AppId: process.env.DOJAH_APP_ID,
  },
});
const data = await res.json();

import os, requests

res = requests.get(
    "https://api.dojah.io/api/v1/kyc/bvn/full",
    headers={
        "Authorization": os.environ["DOJAH_SECRET_KEY"],
        "AppId": os.environ["DOJAH_APP_ID"],
    },
    params={ "bvn": "22222222222" },
)
data = res.json()

{
  "entity": {
    "bvn": "2*****234567",
    "first_name": "JOHN",
    "last_name": "MUSA",
    "middle_name": "DOE",
    "gender": "Male",
    "date_of_birth": "1997-05-16",
    "phone_number1": "08012345678",
    "image": "BASE 64 IMAGE",
    "phone_number2": "08012345678"
  }
}

GET/api/v1/kyc/bvn/full

Retrieve the record tied to a Bank Verification Number (BVN). Use the advanced variant for enrollment and address details.

For new customers using a direct API integration: Dojah is no longer selling BVN Basic and BVN Advance. BVN Validate is available via API. BVN Basic and BVN Advance remain available on the Government Data step of the EasyOnboard widget.

Headers

Header	Required	Description
`Authorization`	Yes	Your app’s secret key, sent as-is — not `Bearer`.
`AppId`	Yes	The App ID from your dashboard.

Query parameters

Parameter	Type	Required	Description
`bvn`	string	Yes	A valid 11-digit Bank Verification Number.

Response

Returns an entity with the holder’s name, gender, date of birth, registered phone numbers, and a base64 image. The bvn is masked.

Advanced lookup

Call GET /api/v1/kyc/bvn/advance with the same bvn to also get enrollment bank/branch, account level, residence and origin details.

200 — /api/v1/kyc/bvn/advance

{
  "entity": {
    "bvn": "2*****234567",
    "first_name": "JOHN",
    "last_name": "MUSA",
    "middle_name": "DOE",
    "gender": "Male",
    "date_of_birth": "1997-05-16",
    "phone_number1": "08012345678",
    "image": "BASE 64 IMAGE",
    "email": "johndoe@gmail.com",
    "enrollment_bank": "GTB",
    "enrollment_branch": "IKEJA",
    "level_of_account": "LEVEL 2",
    "lga_of_origin": "OSOGBO",
    "lga_of_residence": "IKEJA",
    "marital_status": "SINGLE",
    "nationality": "NIGERIAN",
    "phone_number2": "08012345678",
    "state_of_origin": "OSUN",
    "state_of_residence": "LAGOS",
    "title": "MISS",
    "watch_listed": "NO"
  }
}

Errors

Code	Meaning
`400`	Bad request — a required parameter is missing or malformed.
`401`	Unauthorized — check your key and `AppId` (no `Bearer` prefix).
`402`	Insufficient wallet balance. Fund your wallet.
`404`	No record found for the supplied identifier.
`424`	The upstream source was unavailable — retry shortly.
`429`	Too many requests — back off and retry.

Sandbox

Test with bvn=22222222222 against https://sandbox.dojah.io. See Sandbox & test data for every test value.

curl --request GET \
  "https://api.dojah.io/api/v1/kyc/bvn/full?bvn=22222222222" \
  -H "Authorization: {{secret_key}}" \
  -H "AppId: {{app_id}}"

const params = new URLSearchParams({
  "bvn": "22222222222",
});

const url = "https://api.dojah.io/api/v1/kyc/bvn/full?" + params;
const res = await fetch(url, {
  headers: {
    Authorization: process.env.DOJAH_SECRET_KEY,
    AppId: process.env.DOJAH_APP_ID,
  },
});
const data = await res.json();

import os, requests

res = requests.get(
    "https://api.dojah.io/api/v1/kyc/bvn/full",
    headers={
        "Authorization": os.environ["DOJAH_SECRET_KEY"],
        "AppId": os.environ["DOJAH_APP_ID"],
    },
    params={ "bvn": "22222222222" },
)
data = res.json()

{
  "entity": {
    "bvn": "2*****234567",
    "first_name": "JOHN",
    "last_name": "MUSA",
    "middle_name": "DOE",
    "gender": "Male",
    "date_of_birth": "1997-05-16",
    "phone_number1": "08012345678",
    "image": "BASE 64 IMAGE",
    "phone_number2": "08012345678"
  }
}

Get started

Core concepts

API Endpoints

Widget SDKs

API clients

Headers

Query parameters

Response

Advanced lookup

Errors

Sandbox

​Headers

​Query parameters

​Response

​Advanced lookup

​Errors

​Sandbox

Headers

Query parameters

Response

Advanced lookup

Errors

Sandbox