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

# Verify Identity

> Look up a Nigerian NIN for ₦120 or BVN for ₦70 per attempt

Retrieves the available person details for a Nigerian NIN or BVN. The endpoint does not compare a submitted name or DOB and does not make a verification decision. Each NIN provider attempt costs **₦120** and each BVN provider attempt costs **₦70**, including attempts that return no person details.

## Headers

<ParamField header="x-api-key" type="string" required>
  An active production FossaPay API key with full permission. The associated business must have completed verification.
</ParamField>

<ParamField header="X-Idempotency-Key" type="string" required>
  A unique key for this logical verification request, up to 255 characters. Retry with the same key and identical body to avoid an additional charge.
</ParamField>

## Body

<ParamField body="method" type="string" required>
  `NIN` or `BVN`.
</ParamField>

<ParamField body="identityNumber" type="string" required>
  The person's 11-digit NIN or BVN. Preserve leading zeros.
</ParamField>

Nigeria is selected automatically. Do not include `country`, names, date of birth, or `consent` in the request body.

## Request

```bash theme={null}
curl --request POST \
  --url https://api-production.fossapay.com/api/v1/kyc/verifications \
  --header "x-api-key: $FOSSAPAY_API_KEY" \
  --header "X-Idempotency-Key: verify-customer-10025-bvn-v1" \
  --header 'Content-Type: application/json' \
  --data '{
    "method": "BVN",
    "identityNumber": "01234567890"
  }'
```

## Response

HTTP `200` returns the result directly:

```json theme={null}
{
  "reference": "11111111-1111-4111-8111-111111111111",
  "method": "BVN",
  "charged": true,
  "feeAmount": "70.00",
  "currency": "NGN",
  "person": {
    "identityNumber": "01234567890",
    "firstName": "Ada",
    "middleName": "Ngozi",
    "lastName": "Okoro",
    "dateOfBirth": "1990-05-15",
    "gender": "female",
    "phoneNumber": "08012345678",
    "email": "ada@example.com",
    "address": "12 Example Street"
  }
}
```

`person` returns the identity number and the available person details. Optional fields are `null` when unavailable. The response does not include provider metadata or a verification decision. The `reference` is FossaPay's identifier for the request.

When no usable person details are returned, the full response has the same shape with `person: null`:

```json theme={null}
{
  "reference": "22222222-2222-4222-8222-222222222222",
  "method": "BVN",
  "charged": true,
  "feeAmount": "70.00",
  "currency": "NGN",
  "person": null
}
```

Both responses represent a charged lookup attempt. Your business decides how to handle the returned details or their absence.

## Idempotency

* An identical completed request with the same key returns the original result and its original fee without another charge, even if the current price has changed.
* Reusing the key with a different request body returns `409`.
* A request still processing may return `409` or `503`. Retry only with the same key and body. If it remains unresolved, contact support with the idempotency key and any returned reference.
* If a request was rejected before verification and no charge was made, correct the issue and use a new key for the new request.

## Errors

| HTTP status | Meaning |
| - | - |
| `400` | Missing or oversized idempotency key, unsupported method, invalid identity number, no active NGN master wallet, or insufficient available balance. |
| `401` | Missing, invalid, inactive, revoked, or non-production API key. |
| `403` | The merchant account is suspended or has not completed business verification. |
| `409` | The idempotency key was reused with different details, or the original request is still processing. |
| `422` | Request body failed field validation. |
| `503` | Verification is temporarily unavailable or a prior request needs reconciliation. Retry the same request with the same key when the outcome is unclear. |

See the [Identity Verification Guide](/guides/identity-verification) for pricing examples and integration steps.


## OpenAPI

````yaml api-reference/openapi.json POST /api/v1/kyc/verifications
openapi: 3.1.0
info:
  title: FossaPay API
  description: >-
    FossaPay API for checkout wallets, master-wallet payouts, identity
    verification, customer management, NGN wallets, crypto wallets, transfers,
    fees, banks, and webhooks.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api-production.fossapay.com
    description: Production server
security:
  - ApiKeyAuth: []
paths:
  /api/v1/kyc/verifications:
    post:
      tags:
        - Identity Verification
      summary: Look up a Nigerian NIN or BVN
      description: >-
        Returns available person details without making a verification decision.
        Charges NGN 120 for each NIN attempt or NGN 70 for each BVN attempt,
        including one that returns no person details. Identical completed
        requests replayed with the same idempotency key incur no additional
        charge.
      operationId: ExternalKycController_verify
      parameters:
        - name: X-Idempotency-Key
          in: header
          required: true
          description: Unique key for this verification request. Maximum 255 characters.
          schema:
            type: string
            minLength: 1
            maxLength: 255
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdentityVerificationRequest'
      responses:
        '200':
          description: Identity lookup attempt completed and charged
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentityVerificationResponse'
        '400':
          description: Invalid request or insufficient NGN balance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Merchant is not eligible
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: Idempotency conflict or request still processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '422':
          description: Body validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '503':
          description: >-
            Verification is temporarily unavailable or a prior request needs
            reconciliation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
components:
  schemas:
    IdentityVerificationRequest:
      type: object
      required:
        - method
        - identityNumber
      properties:
        method:
          type: string
          enum:
            - NIN
            - BVN
        identityNumber:
          type: string
          pattern: ^[0-9]{11}$
          description: 11-digit NIN or BVN; retain leading zeros.
      additionalProperties: false
    IdentityVerificationResponse:
      type: object
      required:
        - reference
        - method
        - charged
        - feeAmount
        - currency
        - person
      properties:
        reference:
          type: string
          format: uuid
        method:
          type: string
          enum:
            - NIN
            - BVN
        charged:
          type: boolean
          const: true
        feeAmount:
          type: string
          description: >-
            New NIN attempts cost 120.00 NGN and new BVN attempts cost 70.00
            NGN. Idempotent replays retain the original fee, including earlier
            prices.
        currency:
          type: string
          const: NGN
        person:
          oneOf:
            - $ref: '#/components/schemas/IdentityVerificationPerson'
            - type: 'null'
      additionalProperties: false
    ApiError:
      type: object
      properties:
        status:
          oneOf:
            - type: string
            - type: boolean
        statusCode:
          type: integer
        message:
          type: string
        error:
          type: string
        code:
          type: string
        errors:
          type: object
          additionalProperties: true
      additionalProperties: true
    IdentityVerificationPerson:
      type: object
      required:
        - identityNumber
        - firstName
        - middleName
        - lastName
        - dateOfBirth
        - gender
        - phoneNumber
        - email
        - address
      properties:
        identityNumber:
          type: string
          pattern: ^[0-9]{11}$
        firstName:
          type:
            - string
            - 'null'
        middleName:
          type:
            - string
            - 'null'
        lastName:
          type:
            - string
            - 'null'
        dateOfBirth:
          type:
            - string
            - 'null'
        gender:
          type:
            - string
            - 'null'
        phoneNumber:
          type:
            - string
            - 'null'
        email:
          type:
            - string
            - 'null'
        address:
          type:
            - string
            - 'null'
      additionalProperties: false
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````

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