# NIN Verification (Premium)

> Everything in NIN Advanced plus demographics, profession, previous names and address, height, title and the signature image.

The Premium tier of [NIN Verification](https://speedmap.io/docs/products/nin): everything in [Advanced](https://speedmap.io/docs/products/nin_advanced) plus demographics, profession, previous names and address, height, title and the signature image. Same lookup, methods, consent and purpose codes; a separate product with its own price and access.

`POST /v1/verify/nin/premium`

- **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: "premium"` (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](https://speedmap.io/docs/products/nin) | `POST /v1/verify/nin` | Names, gender, date of birth, phone number and photo (plus the residential address and origin when NIMC returns them). |
| [Advanced](https://speedmap.io/docs/products/nin_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](https://speedmap.io/docs/products/nin_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: `nin`)**

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `method` | string | Yes | Always `nin`. |
| `nin` | string | Yes | Format: 11 digits. |
| `reason` | string | Yes | Purpose of the check. One of the 38 NIMC purpose codes. See the [purpose code list](https://speedmap.io/docs/compliance#purpose-codes). |
| `consent` | object | Yes | Your attestation that you obtained the data subject's consent for this purpose. |
| `consent.obtained` | boolean | Yes | Always `true`. |
| `match` | object | No | 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_name` | string | No | Must not be empty. |
| `match.middle_name` | string | No | Must not be empty. |
| `match.last_name` | string | No | Must not be empty. |
| `match.date_of_birth` | string | No | Format: date, `YYYY-MM-DD`. |

**Body parameters (method: `in_person`)**

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `method` | string | Yes | Always `in_person`. |
| `nin` | string | Yes | Format: 11 digits. |
| `selfie_image` | string | Yes | Base64-encoded JPEG selfie. At least 100 characters. |
| `reason` | string | Yes | Purpose of the check. One of the 38 NIMC purpose codes. See the [purpose code list](https://speedmap.io/docs/compliance#purpose-codes). |
| `match` | object | No | 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_name` | string | No | Must not be empty. |
| `match.middle_name` | string | No | Must not be empty. |
| `match.last_name` | string | No | Must not be empty. |
| `match.date_of_birth` | string | No | Format: date, `YYYY-MM-DD`. |

**Body parameters (method: `share_code`)**

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `method` | string | Yes | Always `share_code`. |
| `share_code` | string | Yes | Pattern: `^[A-Za-z0-9]{6}$`. |
| `reason` | string | Yes | Purpose of the check. One of the 38 NIMC purpose codes. See the [purpose code list](https://speedmap.io/docs/compliance#purpose-codes). |
| `match` | object | No | 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_name` | string | No | Must not be empty. |
| `match.middle_name` | string | No | Must not be empty. |
| `match.last_name` | string | No | Must not be empty. |
| `match.date_of_birth` | string | No | Format: date, `YYYY-MM-DD`. |

- Your workspace needs the `nin_premium` 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](https://speedmap.io/docs/idempotency).

_cURL_

```bash
curl -X POST https://api.speedmap.io/v1/verify/nin/premium \
  -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"
  }
}'
```

_Node.js_

```javascript
const res = await fetch("https://api.speedmap.io/v1/verify/nin/premium", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SPEEDMAP_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    "method": "nin",
    "nin": "98765432109",
    "reason": "financialProducts",
    "consent": {
      "obtained": true
    },
    "match": {
      "last_name": "Griffin"
    }
  }),
});

const data = await res.json();
if (!res.ok) throw new Error(data.error.message);
console.log(data);
```

_Python_

```python
import os, uuid, requests

res = requests.post(
    "https://api.speedmap.io/v1/verify/nin/premium",
    headers={
        "Authorization": f"Bearer {os.environ['SPEEDMAP_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "method": "nin",
        "nin": "98765432109",
        "reason": "financialProducts",
        "consent": {
            "obtained": True
        },
        "match": {
            "last_name": "Griffin"
        }
    },
    timeout=30,
)
res.raise_for_status()
data = res.json()
print(data)
```

## Response

A completed check returns `200` with a [verification object](https://speedmap.io/docs/verifications). `status` is `verified` or `not_found`. If the provider has not answered in time you get `202` with `status: "pending"`; [retrieve it later](https://speedmap.io/docs/verifications#pending-verifications) or wait for the `verification.completed` [webhook](https://speedmap.io/docs/webhooks).

**200 OK · assertion**

```json
{
  "reference_id": "spm_8171f3a87cbe221341f7185f",
  "object": "verification",
  "product": "nin_premium",
  "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": "premium",
    "birth_details_present": true,
    "next_of_kin_present": true,
    "demographics_present": true,
    "previous_names_present": false,
    "signature_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": 445,
  "created_at": "2026-10-19T09:41:07.512Z",
  "updated_at": "2026-10-19T09:41:07.874Z"
}
```

**summary**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `first_name` | string | No | First name on the record, masked to its first letter: `A*****`. |
| `last_name` | string | No | Last name on the record, masked to its first letter. |
| `tier` | string | No | `advanced` or `premium`. |
| `birth_details_present` | boolean | No | The record holds at least one of country, state or LGA of birth. |
| `next_of_kin_present` | boolean | No | The record holds a next of kin. |
| `demographics_present` | boolean | No | The record holds at least one demographic field. |
| `previous_names_present` | boolean | No | The record holds previous or maiden names. |
| `signature_present` | boolean | No | The record holds a signature image. |

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](https://speedmap.io/docs/response-shaping).

**Full tier only**

```json
{
  "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": "premium",
    "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"
    },
    "demographics": {
      "marital_status": "single",
      "religion": "CHRISTIANITY",
      "educational_level": "TERTIARY",
      "employment_status": "EMPLOYED",
      "spoken_language": "ENGLISH, IGBO"
    },
    "profession": "MEDICAL DOCTOR",
    "title": "DR",
    "height": "168",
    "previous_names": null,
    "previous_address": null,
    "signature": "/9j/2wBDAAcHBwcHBwgJCQgLDAsM…"
  }
}
```

**data: what NIN Verification (Premium) adds**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `tier` | string | No | `advanced` or `premium`. |
| `birth` | object | No | `country`, `state` and `lga` of birth. Each is `null` when NIMC does not hold it. |
| `address` | object | No | Residence: `residential` (address line), `town`, `lga`, `state`. |
| `origin` | object | No | State, LGA and town of origin. |
| `residence_status` | string \| null | No | Residence status as recorded by NIMC. |
| `next_of_kin` | object \| null | No | `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. |
| `demographics` | object | No | `marital_status`, `religion`, `educational_level`, `employment_status`, `spoken_language`. Each is `null` when not held. |
| `profession` | string \| null | No | Profession as recorded by NIMC. |
| `title` | string \| null | No | Title, for example `MR`, `MRS` or `DR`. |
| `height` | string \| null | No | Height in centimetres, as recorded. |
| `previous_names` | object \| null | No | Previous or maiden `first_name`, `middle_name`, `last_name`. `null` when there are none. |
| `previous_address` | string \| null | No | Previous address, when recorded. |
| `signature` | string \| null | No | Signature image, Base64 JPEG (a display-sized copy, like `photo`). `null` when NIMC holds no signature. |

## Test values

Send these bodies with a sandbox key. More outcome triggers are on the [Sandbox](https://speedmap.io/docs/sandbox) page.

**Verified (Clarke Griffin)**

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

**Verified (Bellamy Blake)**

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

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

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

**Previous surname on record (John Murphy)**

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

**Share code**

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

**Not found**

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

**Provider timeout (resolves on requery)**

```json
{
  "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](https://speedmap.io/docs/errors) for the full list.

---

Source: https://speedmap.io/docs/products/nin_premium