Premium NIN Lookup

curl --request GET \
  "https://api.dojah.io/api/v1/kyc/nin/premium?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/premium?" + 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/premium",
    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",
    "employment_status": "unemployed",
    "birth_country": "nigeria",
    "birth_lga": "Ikeja",
    "birth_state": "Lagos",
    "educational_level": "tertiary",
    "nspoken_lang": "YORUBA",
    "ospoken_lang": "ENGLISH",
    "profession": "STUDENT",
    "religion": "christianity",
    "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",
    "height": "171",
    "title": "mr",
    "signature": "/9j/4AAQSkZJRgABAQEAlgCWAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL....",
    "p_first_name": "",
    "p_middle_name": "",
    "p_last_name": "",
    "p_town": "",
    "p_lga": "",
    "p_address_line_1": "",
    "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/premium

The fullest NIN record NIMC holds. Premium returns everything Advanced NIN does, plus demographic detail (education, religion, languages, profession, height), the holder’s previous name and address, and a base64-encoded signature.

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/premium?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.The same flag works on Advanced NIN.

Response

Returns an entity with the holder’s core identity, residence and origin, next of kin, and the demographic fields unique to this tier.

Identity

Field	Type	Description
`entity.nin`	string	The NIN used for the lookup
`entity.title`	string	Title on record, e.g. `mr`
`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.height`	string	Height in centimetres
`entity.photo`	string	Base64-encoded photograph
`entity.signature`	string	Base64-encoded specimen signature

Demographics

Only returned on Premium.

Field	Type	Description
`entity.employment_status`	string	Employment status on record
`entity.profession`	string	Stated profession
`entity.educational_level`	string	Highest level of education
`entity.religion`	string	Stated religion
`entity.nspoken_lang`	string	Native spoken language
`entity.ospoken_lang`	string	Other spoken language

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

Previous details

Returned as empty strings when the holder has no previous record.

Field	Type	Description
`entity.p_first_name`	string	Previous first name
`entity.p_middle_name`	string	Previous middle name
`entity.p_last_name`	string	Previous surname
`entity.p_address_line_1`	string	First line of the previous address
`entity.p_town`	string	Previous town
`entity.p_lga`	string	Previous LGA

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

Premium returns the widest set of personal data of any NIN lookup, including biometrics (photo, signature), addresses, third-party details for the next of kin, and — with nin_tin=true — tax identifiers. Request it only when your use case needs those fields, store the minimum, keep it encrypted at rest, and never write these values to logs.

Choosing a tier

	Basic	Advanced	Premium
Names, DOB, gender, phone	Yes	Yes	Yes
Photo	Yes	Yes	Yes
Birth, residence and origin	No	Yes	Yes
Next of kin	No	Yes	Yes
Demographics and profession	No	No	Yes
Previous name and address	No	No	Yes
Signature, height, title	No	No	Yes
Tax details (`tax_id`, `tax_residency`)	No	Opt in with `nin_tin=true`	Opt in with `nin_tin=true`

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/premium?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/premium?" + 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/premium",
    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",
    "employment_status": "unemployed",
    "birth_country": "nigeria",
    "birth_lga": "Ikeja",
    "birth_state": "Lagos",
    "educational_level": "tertiary",
    "nspoken_lang": "YORUBA",
    "ospoken_lang": "ENGLISH",
    "profession": "STUDENT",
    "religion": "christianity",
    "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",
    "height": "171",
    "title": "mr",
    "signature": "/9j/4AAQSkZJRgABAQEAlgCWAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL....",
    "p_first_name": "",
    "p_middle_name": "",
    "p_last_name": "",
    "p_town": "",
    "p_lga": "",
    "p_address_line_1": "",
    "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

Premium NIN Lookup

Headers

Query parameters

Getting tax details with nin_tin

Response

Identity

Demographics

Birth, residence and origin

Previous details

Next of kin

Tax details

Choosing a tier

Errors

Sandbox

​Headers

​Query parameters

Getting tax details with nin_tin

​Response

​Identity

​Demographics

​Birth, residence and origin

​Previous details

​Next of kin

​Tax details

​Choosing a tier

​Errors

​Sandbox

Headers

Query parameters

Response

Identity

Demographics

Birth, residence and origin

Previous details

Next of kin

Tax details

Choosing a tier

Errors

Sandbox