> ## 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. # Validate BVN > Confirm that a name and/or date of birth match a BVN. Does not return the full record or photo. Charged from your NGN wallet when the provider answers. Scope: `identity:write`. Requires `Idempotency-Key`. > [!NOTE] > > Part of **Identity**. List prices first with [List products](https://docs.sendpadi.com/api-reference/identity/list-products.md). Live keys debit your **NGN wallet** when the provider answers (found or not found). Provider-down errors are refunded. **1. Confirm price** `GET /api/v1/merchant/identity/products` → copy `price` for `bvn_basic`. Skip products where `available` is `false`. **2. Verify** `POST /api/v1/merchant/identity/bvn/basic` with `bvn` (11 digits), an `Idempotency-Key`, and at least one of `firstName`, `lastName`, `dateOfBirth`. `lookupType` is `validate`. `record` is always `null`. **`passed` is the overall result** — use this, not HTTP `201` / `success: true` (those only mean the lookup finished and was charged). `true` when the BVN is recognised and every field you sent matched. `match.bvn.value` is masked. `dateOfBirth.confidenceValue` may be `null` when the provider only returns `status`. > [!NOTE] > > **Sandbox (test keys):** any 11-digit number returns a sample payload and **does not debit** your wallet. All zeros (`00000000000`) returns `IDENTITY_NOT_FOUND`. ## OpenAPI ````yaml POST /api/v1/merchant/identity/bvn/basic openapi: 3.1.0 info: title: SendPadi Merchant API version: 1.0.0 description: >- Merchant REST API. Authenticate with HMAC headers (`X-Api-Key`, `X-Timestamp`, `X-Signature`). Generate playground headers with [Sign requests (playground)](/guides/sign-requests). servers: - url: https://api.sendpadi.com description: Production (test + live keys) security: [] paths: /api/v1/merchant/identity/bvn/basic: post: tags: - identity summary: Validate BVN description: >- Confirm that a name and/or date of birth match a BVN. Does not return the full record or photo. Charged from your NGN wallet when the provider answers. **Scope:** `identity:write`. Requires `Idempotency-Key` on this write. operationId: api-reference_identity_verify-bvn-basic parameters: - name: X-Timestamp in: header required: true description: Unix time in seconds schema: type: string - name: X-Signature in: header required: true description: HMAC-SHA256 signature schema: type: string - name: Idempotency-Key in: header required: true description: UUID. Required on money-moving writes. schema: type: string format: uuid requestBody: required: true content: application/json: schema: type: object properties: bvn: type: string description: 11-digit BVN. Digits only. firstName: type: string description: >- Sent to Validate BVN as `first_name`. At least one of firstName, lastName, or dateOfBirth is required. lastName: type: string description: Sent to Validate BVN as `last_name`. dateOfBirth: type: string description: Sent to Validate BVN as `dob`. `YYYY-MM-DD` or `DD-MM-YYYY`. required: - bvn example: bvn: '22222222222' firstName: John lastName: Doe dateOfBirth: '1990-01-01' responses: '201': description: OK content: application/json: schema: type: object additionalProperties: true example: success: true data: transactionId: idv_txn_001 reference: IDV-abc status: completed product: bvn_basic idType: bvn level: basic charge: amount: 70 currency: NGN lookupType: validate passed: true record: null match: bvn: value: 2****2222 status: true firstName: status: true confidenceValue: 100 lastName: status: true confidenceValue: 100 dateOfBirth: status: true confidenceValue: null examples: success: summary: Success value: success: true data: transactionId: idv_txn_001 reference: IDV-abc status: completed product: bvn_basic idType: bvn level: basic charge: amount: 70 currency: NGN lookupType: validate passed: true record: null match: bvn: value: 2****2222 status: true firstName: status: true confidenceValue: 100 lastName: status: true confidenceValue: 100 dateOfBirth: status: true confidenceValue: null '400': description: Name or date of birth required content: application/json: schema: type: object additionalProperties: true examples: name_or_date_of_birth_required: summary: Name or date of birth required value: success: false message: >- BVN validate requires at least one of firstName, lastName, or dateOfBirth. error: IDENTITY_MATCH_FIELDS_REQUIRED insufficient_ngn_balance: summary: Insufficient NGN balance value: success: false message: >- Insufficient funds. BVN costs 70 NGN; your available balance is 0 NGN. error: INSUFFICIENT_BALANCE example: success: false message: >- BVN validate requires at least one of firstName, lastName, or dateOfBirth. error: IDENTITY_MATCH_FIELDS_REQUIRED '404': description: No record found (charged) content: application/json: schema: type: object additionalProperties: true examples: no_record_found_charged_: summary: No record found (charged) value: success: false message: >- No record was found for this BVN. The lookup was completed and has been charged. error: IDENTITY_NOT_FOUND data: transactionId: idv_txn_001 reference: IDV-abc status: completed refunded: false charge: amount: 70 currency: NGN example: success: false message: >- No record was found for this BVN. The lookup was completed and has been charged. error: IDENTITY_NOT_FOUND data: transactionId: idv_txn_001 reference: IDV-abc status: completed refunded: false charge: amount: 70 currency: NGN '503': description: Provider unavailable (refunded) content: application/json: schema: type: object additionalProperties: true examples: provider_unavailable_refunded_: summary: Provider unavailable (refunded) value: success: false message: >- BVN verification is temporarily unavailable. Please try again shortly. You have not been charged. error: IDENTITY_PROVIDER_UNAVAILABLE data: transactionId: idv_txn_001 reference: IDV-abc status: failed refunded: true charge: amount: 70 currency: NGN example: success: false message: >- BVN verification is temporarily unavailable. Please try again shortly. You have not been charged. error: IDENTITY_PROVIDER_UNAVAILABLE data: transactionId: idv_txn_001 reference: IDV-abc status: failed refunded: true charge: amount: 70 currency: NGN security: - ApiKeyAuth: [] components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-Api-Key description: API key id (sp_test_… / sp_live_…) ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.