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

# Identity overview

> Validate a BVN, look up a full BVN record, or look up a NIN. List products for your price, then call the matching verify endpoint.

# Identity verification

Base path: `/api/v1/merchant/identity`

Scopes: `identity:read`, `identity:write`. Lookups require **Idempotency-Key**.

Live keys debit your **NGN wallet** whenever the identity provider answers — including `IDENTITY_NOT_FOUND`. Only provider-down (`503`) lookups are refunded.

## Typical flow

1. **List products** — confirm `price` and that `available` is `true`.
2. **Verify** — `POST /identity/bvn/basic` (validate), `bvn/enhanced` (full record), `nin/basic`, or `nin/enhanced`.
3. **Body** — BVN validate requires `bvn` plus at least one of `firstName`, `lastName`, `dateOfBirth`. BVN full and NIN require only the 11-digit number; match fields are optional and do not change the record returned.

## Products

| Product | Path | What you get |
| - | - | - |
| BVN validate (`bvn_basic`) | `POST /identity/bvn/basic` | `lookupType: validate`. `passed` is the overall match. `record` is `null` (no photo). |
| BVN full (`bvn_enhanced`) | `POST /identity/bvn/enhanced` | `lookupType: record`. Full biodata + photo, plus email/address/enrollment when available. |
| NIN basic | `POST /identity/nin/basic` | `lookupType: record`. Name, DOB, gender, phone, photo. |
| NIN enhanced | `POST /identity/nin/enhanced` | `lookupType: record`. Basic + email, address when available. |

`bvn` / `nin` must be **11 digits**. Do not send spaces or hyphens.

## Charging

| Outcome | HTTP | Wallet |
| - | - | - |
| Validate or record returned | `201` | Debited `charge.amount` NGN (including `passed: false`) |
| No record | `404` `IDENTITY_NOT_FOUND` | Debited (the provider answered) |
| Provider down | `503` `IDENTITY_PROVIDER_UNAVAILABLE` | Refunded |
| Product not priced | `400` `MERCHANT_PRICE_NOT_SET` | Not charged |
| Insufficient NGN | `400` `INSUFFICIENT_BALANCE` | Not charged |
| BVN validate missing name/DOB | `400` `IDENTITY_MATCH_FIELDS_REQUIRED` | Not charged |

Test keys (`sp_test_`) simulate the same responses and **do not debit**. Use `00000000000` to exercise the not-found path.

## `match` on BVN validate

`success: true` means the lookup completed. **`passed`** is whether the name/DOB matched: `true` when the BVN is recognised and every field you sent matched. `match.bvn.value` is masked (not the full 11 digits).

| Field | Meaning |
| - | - |
| `passed` | Overall pass/fail for this validate call |
| `bvn.value` / `bvn.status` | Masked BVN and whether it was recognised |
| `firstName` / `lastName` / `dateOfBirth` | `status` plus `confidenceValue` (0–100) for each field you sent; omitted fields are `null` |

Do not send `middleName` or `phoneNumber` on BVN validate.

## `match` on lookup products (BVN full, NIN)

| Field | How it is compared |
| - | - |
| `firstName` / `middleName` / `lastName` | Case-insensitive letters only |
| `dateOfBirth` | `YYYY-MM-DD` or `DD-MM-YYYY` |
| `phoneNumber` | Last 10 digits |
| `nameMatchPercentage` | Share of the name tokens you sent that appear on the record (0–100), or `null` if you sent no names |


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