> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fastcac.com/llms.txt
> Use this file to discover all available pages before exploring further.

# NIN lookups

> Get what NIMC holds for a proprietor's NIN, prefill your form and use their photo as the passport.

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.

```bash theme={null}
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}'
```

```json Response (201, photo shortened) theme={null}
{
  "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](https://docs.fastcac.com/guides/balance.md#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`:

```json theme={null}
"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.

```json theme={null}
{
  "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.

```bash theme={null}
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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.