Advanced NIN Lookup

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

const params = new URLSearchParams({
  "nin": "70123456789",
});

const url = "https://api.dojah.io/api/v1/kyc/nin/advance?" + 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/nin/advance",
    headers={
        "Authorization": os.environ["DOJAH_SECRET_KEY"],
        "AppId": os.environ["DOJAH_APP_ID"],
    },
    params={ "nin": "70123456789" },
)
data = res.json()

{
  "entity": {
    "nin": "70123456789",
    "first_name": "JOHN",
    "last_name": "ADAMU",
    "middle_name": "DOE",
    "date_of_birth": "1990-01-01",
    "phone_number": "08012345678",
    "photo": "/9j/4AAQSkZJRgABAgAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL....",
    "gender": "Male",
    "birth_country": "nigeria",
    "birth_lga": "Ikeja",
    "birth_state": "Lagos",
    "residence_address_line_1": "1, EXAMPLE STREET",
    "residence_status": "birth",
    "residence_town": "IKEJA",
    "residence_lga": "Ikeja",
    "residence_state": "Lagos",
    "origin_lga": "Ikeja",
    "origin_place": "IKEJA",
    "origin_state": "Lagos",
    "nok_first_name": "JANE",
    "nok_middle_name": "AMINA",
    "nok_last_name": "ADAMU",
    "nok_town": "IKEJA",
    "nok_lga": "Ikeja",
    "nok_address_line_1": "1, EXAMPLE STREET"
  }
}

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

const params = new URLSearchParams({
  "nin": "70123456789",
});

const url = "https://api.dojah.io/api/v1/kyc/nin/advance?" + 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/nin/advance",
    headers={
        "Authorization": os.environ["DOJAH_SECRET_KEY"],
        "AppId": os.environ["DOJAH_APP_ID"],
    },
    params={ "nin": "70123456789" },
)
data = res.json()

{
  "entity": {
    "nin": "70123456789",
    "first_name": "JOHN",
    "last_name": "ADAMU",
    "middle_name": "DOE",
    "date_of_birth": "1990-01-01",
    "phone_number": "08012345678",
    "photo": "/9j/4AAQSkZJRgABAgAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL....",
    "gender": "Male",
    "birth_country": "nigeria",
    "birth_lga": "Ikeja",
    "birth_state": "Lagos",
    "residence_address_line_1": "1, EXAMPLE STREET",
    "residence_status": "birth",
    "residence_town": "IKEJA",
    "residence_lga": "Ikeja",
    "residence_state": "Lagos",
    "origin_lga": "Ikeja",
    "origin_place": "IKEJA",
    "origin_state": "Lagos",
    "nok_first_name": "JANE",
    "nok_middle_name": "AMINA",
    "nok_last_name": "ADAMU",
    "nok_town": "IKEJA",
    "nok_lga": "Ikeja",
    "nok_address_line_1": "1, EXAMPLE STREET"
  }
}

GET/api/v1/kyc/nin/advance

A richer NIN lookup — the standard identity data plus birth, residence, origin and next-of-kin details, for compliance and risk.

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
`nin`	string	Yes	A valid 11-digit National Identity Number.
`nin_tin`	boolean	No	Set to `true` to also return the holder’s tax details — `tax_id` and `tax_residency`. Omitted or `false` returns the standard record without them.

Getting tax details with nin_tin

tax_id and tax_residency are not part of the default response. To get them, add nin_tin=true to the query:

GET /api/v1/kyc/nin/advance?nin=70123456789&nin_tin=true

The two tax fields are then appended to the same entity object — everything else in the response is unchanged. Treat them as optional in your code: parse them defensively, since they are absent whenever nin_tin is off and may come back empty if the holder has no TIN on record.

Response

Returns an entity with the holder’s names, gender, date of birth, phone number, and a base64-encoded photo — plus the fields the basic lookup doesn’t carry: birth details, full residence and origin, and next of kin.

Identity

Field	Type	Description
`entity.nin`	string	The NIN used for the lookup
`entity.first_name`	string	First name of the holder
`entity.middle_name`	string	Middle name of the holder
`entity.last_name`	string	Surname of the holder
`entity.date_of_birth`	string	Date of birth, `YYYY-MM-DD`
`entity.gender`	string	Gender of the holder
`entity.phone_number`	string	Phone number linked to the NIN
`entity.photo`	string	Base64-encoded photograph

Birth, residence and origin

Field	Type	Description
`entity.birth_country`	string	Country of birth
`entity.birth_state`	string	State of birth
`entity.birth_lga`	string	LGA of birth
`entity.residence_address_line_1`	string	First line of the registered residential address
`entity.residence_town`	string	Town of residence
`entity.residence_lga`	string	LGA of residence
`entity.residence_state`	string	State of residence
`entity.residence_status`	string	Basis of residence, e.g. `birth`
`entity.origin_place`	string	Place of origin
`entity.origin_lga`	string	LGA of origin
`entity.origin_state`	string	State of origin

Next of kin

Field	Type	Description
`entity.nok_first_name`	string	Next of kin’s first name
`entity.nok_middle_name`	string	Next of kin’s middle name
`entity.nok_last_name`	string	Next of kin’s surname
`entity.nok_address_line_1`	string	First line of the next of kin’s address
`entity.nok_town`	string	Next of kin’s town
`entity.nok_lga`	string	Next of kin’s LGA

Tax details

Only returned when you pass nin_tin=true.

Field	Type	Description
`entity.tax_id`	string	Taxpayer Identification Number (TIN) tied to the holder
`entity.tax_residency`	string	State tax authority the holder is registered with

The photo, address, next-of-kin, and tax fields are sensitive personal data — the next-of-kin fields describe a third party who did not initiate your check. Store only what you need, keep it encrypted at rest, and never write these values to logs.

Need demographics, profession, previous name and address, or the holder’s signature? Use Premium NIN, which returns everything below plus those fields.

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 nin=70123456789 against https://sandbox.dojah.io. See Sandbox & test data for every test value.

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

const params = new URLSearchParams({
  "nin": "70123456789",
});

const url = "https://api.dojah.io/api/v1/kyc/nin/advance?" + 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/nin/advance",
    headers={
        "Authorization": os.environ["DOJAH_SECRET_KEY"],
        "AppId": os.environ["DOJAH_APP_ID"],
    },
    params={ "nin": "70123456789" },
)
data = res.json()

{
  "entity": {
    "nin": "70123456789",
    "first_name": "JOHN",
    "last_name": "ADAMU",
    "middle_name": "DOE",
    "date_of_birth": "1990-01-01",
    "phone_number": "08012345678",
    "photo": "/9j/4AAQSkZJRgABAgAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL....",
    "gender": "Male",
    "birth_country": "nigeria",
    "birth_lga": "Ikeja",
    "birth_state": "Lagos",
    "residence_address_line_1": "1, EXAMPLE STREET",
    "residence_status": "birth",
    "residence_town": "IKEJA",
    "residence_lga": "Ikeja",
    "residence_state": "Lagos",
    "origin_lga": "Ikeja",
    "origin_place": "IKEJA",
    "origin_state": "Lagos",
    "nok_first_name": "JANE",
    "nok_middle_name": "AMINA",
    "nok_last_name": "ADAMU",
    "nok_town": "IKEJA",
    "nok_lga": "Ikeja",
    "nok_address_line_1": "1, EXAMPLE STREET"
  }
}

Get started

Core concepts

API Endpoints

Widget SDKs

API clients

Advanced NIN Lookup

Headers

Query parameters

Getting tax details with nin_tin

Response

Identity

Birth, residence and origin

Next of kin

Tax details

Errors

Sandbox

​Headers

​Query parameters

Getting tax details with nin_tin

​Response

​Identity

​Birth, residence and origin

​Next of kin

​Tax details

​Errors

​Sandbox

Headers

Query parameters

Response

Identity

Birth, residence and origin

Next of kin

Tax details

Errors

Sandbox