NIN Verification (Advanced)

Everything in NIN Verification plus birth details, full residence and origin, and next of kin from the NIMC record.

The Advanced tier of NIN Verification: the same lookup, methods, consent and purpose codes, returning everything in Basic plus birth details, the full residence and origin, and next of kin from the NIMC record. It is a separate product with its own price and access.

POST/v1/verify/nin/advanced

Availability: Sandbox and live
Consent: Same as Basic: your attestation (nin), the live selfie (in_person) or the NINAuth share code (share_code).
MCP tool: verify_nin with tier: "advanced" (presence flags only; the record stays in the REST API and dashboard)

Choose a tier

NIN verification comes in three tiers. Each is its own endpoint and product, with its own price and access; the request body, methods, consent and purpose codes are the same for all three.

Tier	Endpoint	What it adds
Basic	`POST /v1/verify/nin`	Names, gender, date of birth, phone number and photo (plus the residential address and origin when NIMC returns them).
Advanced	`POST /v1/verify/nin/advanced`	Everything in Basic, plus country, state and LGA of birth; full residence (address, town, LGA, state) and state, LGA and town of origin; next of kin (name, relationship where recorded, address, town, LGA, state).
Premium	`POST /v1/verify/nin/premium`	Everything in Advanced, plus marital status, religion, educational level, employment status, spoken language, profession, previous or maiden names and previous address where recorded, height, title and the signature image.

Methods

Choose a method with the method field. Each one has its own required fields and consent mechanism.

method	Description	Required fields
`nin`	Raw NIN lookup. Restricted by NIMC to financial institutions and government agencies.	`nin`, `reason`, `consent`
`in_person`	NIN plus a live selfie. The selfie is the consent. Available to all business types.	`nin`, `selfie_image`, `reason`
`share_code`	6-character code the subject generates in the NINAuth app. The code is the consent.	`share_code`, `reason`

Request

Body parameters · method

Raw NIN lookup. Restricted by NIMC to financial institutions and government agencies.

methodstringrequired
Always nin.
ninstringrequired
Format: 11 digits.
reasonstringrequired
Purpose of the check. One of the 38 NIMC purpose codes. See the purpose code list.
consentobjectrequired
Your attestation that you obtained the data subject's consent for this purpose.
consent.obtainedbooleanrequired
Always true.
matchobject
Optional values to compare against the record. Each comparison is returned in field_matches; match is true only if all of them agree.
match.first_namestring
Must not be empty.
match.middle_namestring
Must not be empty.
match.last_namestring
Must not be empty.
match.date_of_birthstring
Format: date, YYYY-MM-DD.

NIN plus a live selfie. The selfie is the consent. Available to all business types.

methodstringrequired
Always in_person.
ninstringrequired
Format: 11 digits.
selfie_imagestringrequired
Base64-encoded JPEG selfie. At least 100 characters.
reasonstringrequired
Purpose of the check. One of the 38 NIMC purpose codes. See the purpose code list.
matchobject
Optional values to compare against the record. Each comparison is returned in field_matches; match is true only if all of them agree.
match.first_namestring
Must not be empty.
match.middle_namestring
Must not be empty.
match.last_namestring
Must not be empty.
match.date_of_birthstring
Format: date, YYYY-MM-DD.

6-character code the subject generates in the NINAuth app. The code is the consent.

methodstringrequired
Always share_code.
share_codestringrequired
Pattern: ^[A-Za-z0-9]{6}$.
reasonstringrequired
Purpose of the check. One of the 38 NIMC purpose codes. See the purpose code list.
matchobject
Optional values to compare against the record. Each comparison is returned in field_matches; match is true only if all of them agree.
match.first_namestring
Must not be empty.
match.middle_namestring
Must not be empty.
match.last_namestring
Must not be empty.
match.date_of_birthstring
Format: date, YYYY-MM-DD.

Your workspace needs the nin_advanced entitlement. Raw NIN (method: "nin") also needs raw NIN access, exactly as on Basic.
method: "nin" (raw NIN lookup) is restricted by NIMC to financial institutions and government agencies. Other accounts receive 403 not_entitled; use in_person or share_code.
share_code checks carry no NIN, so subject is null in the response.
If NIMC does not answer in time the response is 202 with status: "pending". Read it again with GET /v1/verifications/{reference_id}: pending NIN checks are re-queried on read.
Fields NIMC does not return come back as null; Speedmap never fills them in. summary only says whether each section is present.

Send an Idempotency-Key header so a retried request is never billed twice. See Idempotency.

curl -X POST https://api.speedmap.io/v1/verify/nin/advanced \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "method": "nin",
  "nin": "98765432109",
  "reason": "financialProducts",
  "consent": {
    "obtained": true
  },
  "match": {
    "last_name": "Griffin"
  }
}'

Response

A completed check returns 200 with a verification object. status is verified or not_found. If the provider has not answered in time you get 202 with status: "pending"; retrieve it later or wait for the verification.completed webhook.

200 OK · assertion

{
  "reference_id": "spm_8171f3a87cbe221341f7185f",
  "object": "verification",
  "product": "nin_advanced",
  "method": "nin_raw",
  "status": "verified",
  "match": true,
  "field_matches": {
    "last_name": true
  },
  "field_confidence": {
    "last_name": 100
  },
  "mode": "sandbox",
  "reason": "financialProducts",
  "subject": "*******2109",
  "summary": {
    "first_name": "C*****",
    "last_name": "G******",
    "tier": "advanced",
    "birth_details_present": true,
    "next_of_kin_present": true
  },
  "consent": {
    "mechanism": "client_attested",
    "consent_id": null,
    "timestamp": "2026-10-19T09:41:07.512Z"
  },
  "source": "api",
  "error": null,
  "billing": {
    "amount_kobo": 0,
    "currency": "NGN"
  },
  "latency_ms": 430,
  "created_at": "2026-10-19T09:41:07.512Z",
  "updated_at": "2026-10-19T09:41:07.874Z"
}

summary

first_namestring
First name on the record, masked to its first letter: A*****.
last_namestring
Last name on the record, masked to its first letter.
tierstring
advanced or premium.
birth_details_presentboolean
The record holds at least one of country, state or LGA of birth.
next_of_kin_presentboolean
The record holds a next of kin.

Full-tier accounts calling the REST API also receive provider, provider_reference and data, the normalized record. MCP, webhooks, lists and bulk results never include it. See Response shaping.

Full tier only

{
  "provider": "sandbox",
  "provider_reference": "SBX6CB753DB2C",
  "data": {
    "first_name": "CLARKE",
    "middle_name": "ELIZA",
    "last_name": "GRIFFIN",
    "date_of_birth": "1992-04-18",
    "gender": "female",
    "phone": "08031234567",
    "address": {
      "residential": "14 ADEOLA ODEKU STREET",
      "town": "VICTORIA ISLAND",
      "state": "Lagos",
      "lga": "Eti-Osa"
    },
    "origin": {
      "state": "Enugu",
      "lga": "Nsukka",
      "town": "NSUKKA"
    },
    "photo": "/9j/2wBDAAcHBwcHBwgJCQgLDAsM…",
    "tier": "advanced",
    "birth": {
      "country": "Nigeria",
      "state": "Enugu",
      "lga": "Nsukka"
    },
    "residence_status": "birth",
    "next_of_kin": {
      "first_name": "ABIGAIL",
      "middle_name": null,
      "last_name": "GRIFFIN",
      "relationship": "Mother",
      "address": "2 ARK MEDICAL QUARTERS, UNIVERSITY ROAD",
      "town": "NSUKKA",
      "lga": "Nsukka",
      "state": "Enugu",
      "postal_code": "410001"
    }
  }
}

data: what NIN Verification (Advanced) adds

tierstring
advanced or premium.
birthobject
country, state and lga of birth. Each is null when NIMC does not hold it.
addressobject
Residence: residential (address line), town, lga, state.
originobject
State, LGA and town of origin.
residence_statusstring | null
Residence status as recorded by NIMC.
next_of_kinobject | null
first_name, middle_name, last_name, relationship (often not recorded), address, town, lga, state, postal_code. null when the record has no next of kin.

Test values

Send these bodies with a sandbox key. More outcome triggers are on the Sandbox page.

Verified (Clarke Griffin)

{
  "method": "nin",
  "nin": "98765432109",
  "reason": "financialProducts",
  "consent": {
    "obtained": true
  }
}

Verified (Bellamy Blake)

{
  "method": "nin",
  "nin": "09876543210",
  "reason": "employmentRecruitment",
  "consent": {
    "obtained": true
  }
}

Sparse record (Monty Green: no next of kin or signature)

{
  "method": "nin",
  "nin": "11111111111",
  "reason": "financialProducts",
  "consent": {
    "obtained": true
  }
}

Previous surname on record (John Murphy)

{
  "method": "nin",
  "nin": "22222222222",
  "reason": "financialProducts",
  "consent": {
    "obtained": true
  }
}

Share code

{
  "method": "share_code",
  "share_code": "SPM001",
  "reason": "financialProducts"
}

Not found

{
  "method": "nin",
  "nin": "00000000000",
  "reason": "financialProducts",
  "consent": {
    "obtained": true
  }
}

Provider timeout (resolves on requery)

{
  "method": "nin",
  "nin": "99999999999",
  "reason": "financialProducts",
  "consent": {
    "obtained": true
  }
}

Errors

Status	Code	Meaning
400	`invalid_request`	The body failed validation. `details` lists each field.
401	`unauthorized`	Missing or invalid API key.
402	`insufficient_balance`	Live only: wallet balance is below the check price.
403	`not_entitled`	Your workspace is not enabled for this product or method.
409	`idempotency_key_reused`	The `Idempotency-Key` was used with a different body.
422	`provider_rejected_request`	The upstream registry rejected the request.
503	`verification_unavailable`	Temporary failure. Retry, with the same or a new `Idempotency-Key`.

All errors share one shape. See Errors for the full list.

Questions? Email developers@speedmap.io. This page is also available as Markdown.