NIN lookups

CAC checks a proprietor’s name, gender and date of birth against their NIN, and queries a registration when they don’t match. A NIN lookup gets you NIMC’s own record first, so you can prefill your form from it, have submit catch a mismatch before CAC does, and use NIMC’s photo as the passport. It’s optional: a registration without one works as before.

Look up a NIN

POST /v1/identities/nin_lookups with the NIN and consent: true, your confirmation that the person agreed to the lookup.

curl https://api.fastcac.com/v1/identities/nin_lookups \
  -H "Authorization: Bearer $FASTCAC_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"nin": "12345678901", "consent": true}'

Response (201, photo shortened)

{
  "object": "nin_lookup",
  "id": "ninl_6x9CKdEGQkJAbby8D1u7kN",
  "nin": "12345678901",
  "first_name": "ADA",
  "middle_name": "CHIOMA",
  "last_name": "OBI",
  "gender": "female",
  "date_of_birth": "1990-04-12",
  "phone": "08031234567",
  "address": "12 ADMIRALTY WAY, LEKKI, LAGOS",
  "photo": "data:image/jpeg;base64,/9j/4AAQSkZJRgABA…",
  "nimc_data": {},
  "amount_charged": "100.00",
  "transaction_id": "wtx_0hA6wRH6yeYHTLfRjK4Bxn",
  "created_at": "2026-10-26T05:55:58Z"
}

Field	What it is
`first_name`, `middle_name`, `last_name`	As NIMC holds them, usually upper case. `middle_name` goes in the proprietor’s `other_names`.
`gender`, `date_of_birth`	`male`/`female`, and `YYYY-MM-DD`.
`phone`, `address`	NIMC’s. The address is one line; a registration takes it in parts.
`photo`	NIMC’s photo as a `data:` URI (JPEG).
`nimc_data`	Every other field NIMC returned, as it came.

GET /v1/identities/nin_lookups/{id} returns it again, free. Only your organization, in the same mode, can read it. We keep the record encrypted.

Pricing

A lookup costs ₦100 from the wallet of the key’s mode (test lookups spend test money); the current price is on the Billing page. It shows as a nin_lookup_charge in your transactions.

Outcome	Charged
NIMC’s record	Yes
`422 nin_not_found`: NIMC has no record of the NIN	No (`nin_lookup_refund`)
`503 nin_lookup_unavailable`: the identity service didn’t answer	No (`nin_lookup_refund`)
`402 insufficient_balance`: the wallet can’t cover it. Nothing is looked up.	No
`400 consent_required` or a NIN that isn’t 11 digits	No

Send an Idempotency-Key: a retry with the same key gets the first answer and isn’t charged again. Live lookups allow 60 a minute per organization.

Use it in a registration

Set the proprietor’s nin_lookup to the lookup’s id:

"proprietors": [{
  "nin_lookup": "ninl_6x9CKdEGQkJAbby8D1u7kN",
  "email": "ada@example.com",
  "address": { "street_number": "12", "street": "Admiralty Way", "city": "Lekki",
               "lga": "Eti-Osa", "state": "Lagos", "postcode": "105102" }
}]

Blank fields are filled from NIMC: first_name, last_name, other_names, gender, date_of_birth, nin and phone. Fields you send are kept. A nin that isn’t the lookup’s is 400 parameter_invalid.
Submit checks the match. If first_name, last_name, gender or date_of_birth differs from NIMC’s record (case and spacing don’t count), submit answers 400 nin_mismatch naming the field, before anything is charged. Once CAC queries a registration, its answer wins: a resubmit isn’t checked against the lookup.

{
  "error": {
    "type": "invalid_request_error",
    "code": "nin_mismatch",
    "message": "Doesn't match NIMC's record for this NIN (ADA). CAC would query it.",
    "param": "proprietors[0].first_name"
  }
}

Use the NIN photo as the passport

Instead of uploading a passport photo, send the lookup’s id as nin_lookup (and no file) with kind=passport. NIMC’s photo becomes the passport; CAC accepts it.

curl https://api.fastcac.com/v1/businesses/registrations/$REG_ID/documents \
  -H "Authorization: Bearer $FASTCAC_KEY" \
  -F kind=passport -F proprietor=0 -F nin_lookup=ninl_6x9CKdEGQkJAbby8D1u7kN

You can show the user photo first and let them choose between it and an upload. Only passport takes a nin_lookup, and it must be for the proprietor’s own NIN: set their nin (or their own nin_lookup) first, or it’s 400 parameter_invalid.

Test mode

Test lookups never reach NIMC. Every NIN returns the same test person (ADA CHIOMA OBI, female, 1990-04-12, a plain grey photo). ?simulate=nin_not_found gives the 422 and ?simulate=insufficient_balance the 402.

Get started

Registering a business

Webhooks

API basics

Resources

Going live

Look up a NIN

Pricing

Use it in a registration

Use the NIN photo as the passport

Test mode

​Look up a NIN

​Pricing

​Use it in a registration

​Use the NIN photo as the passport

​Test mode

Look up a NIN

Pricing

Use it in a registration

Use the NIN photo as the passport

Test mode