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

# Verify BVN (basic)

> Performs a basic BVN verification and returns the record's basic details.



## OpenAPI

````yaml /openapi.json post /kyc/identity/bvn/basic
openapi: 3.0.0
info:
  description: |-
    Hyparrow payment gateway API. Authenticate server-to-server
    requests with your API key credentials.
  title: Hyparrow API
  termsOfService: https://hyparrow.cloud/terms
  contact:
    name: Hyparrow Support
    email: support@hyparrow.com
  version: '1.0'
servers:
  - url: https://api.hyparrow.cloud/api/v1
    description: Production
  - url: https://sandbox.hyparrow.cloud/api/v1
    description: Sandbox - simulated providers, test keys only, no real money
security: []
paths:
  /kyc/identity/bvn/basic:
    post:
      tags:
        - KYC
      summary: Verify BVN (basic)
      description: >-
        Performs a basic BVN verification and returns the record's basic
        details.
      requestBody:
        $ref: '#/components/requestBodies/internal_handlers.KYCBVNRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/internal_handlers.KYCBVNBasicResponse'
        '400':
          description: >-
            Request body failed validation. Rejected before the verification
            network was called, so not billed.
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/internal_handlers.KYCValidationErrorResponse
        '401':
          description: Missing or invalid API credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/internal_handlers.KYCErrorResponse'
        '402':
          description: Insufficient wallet balance, or subscription quota exhausted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/internal_handlers.KYCErrorResponse'
        '404':
          description: >-
            No record for the identifier supplied. The charge is rolled back.
            Correct the input; retrying will not help.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/internal_handlers.KYCNotFoundResponse'
        '502':
          description: >-
            The verification network failed or was unreachable. The charge is
            rolled back. Safe to retry with backoff.
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/internal_handlers.KYCUpstreamErrorResponse
      security:
        - ApiKeyAuth: []
components:
  requestBodies:
    internal_handlers.KYCBVNRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/internal_handlers.KYCBVNRequest'
      description: BVN to verify
      required: true
  schemas:
    internal_handlers.KYCBVNBasicResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/internal_handlers.KYCBVNBasicEnvelope'
        success:
          type: boolean
          example: true
    internal_handlers.KYCValidationErrorResponse:
      type: object
      properties:
        code:
          type: string
          example: VALIDATION_ERROR
        error:
          type: string
          example: bvn must be exactly 11 digits
        field:
          description: The JSON field at fault, when the failure is attributable to one.
          type: string
          example: bvn
        success:
          type: boolean
          example: false
    internal_handlers.KYCErrorResponse:
      type: object
      properties:
        code:
          description: |-
            Stable machine-readable classification, e.g. INSUFFICIENT_BALANCE or
            QUOTA_EXCEEDED.
          type: string
          example: INSUFFICIENT_BALANCE
        error:
          type: string
          example: Insufficient verification balance
        success:
          type: boolean
          example: false
    internal_handlers.KYCNotFoundResponse:
      type: object
      properties:
        code:
          type: string
          example: RECORD_NOT_FOUND
        data:
          $ref: '#/components/schemas/internal_handlers.KYCUpstreamMessage'
        error:
          type: string
          example: no record was found for the details provided
        success:
          type: boolean
          example: false
    internal_handlers.KYCUpstreamErrorResponse:
      type: object
      properties:
        code:
          type: string
          example: UPSTREAM_ERROR
        data:
          $ref: '#/components/schemas/internal_handlers.KYCUpstreamMessage'
        error:
          type: string
          example: the verification network is temporarily unavailable
        success:
          type: boolean
          example: false
    internal_handlers.KYCBVNRequest:
      type: object
      required:
        - bvn
      properties:
        bvn:
          description: 11-digit Bank Verification Number.
          type: string
          example: '22222222222'
    internal_handlers.KYCBVNBasicEnvelope:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/internal_handlers.KYCBVNBasicRecord'
        message:
          type: string
          example: Bvn details retrieved successfully
        response_code:
          description: Upstream result code. "00" indicates success.
          type: string
          example: '00'
        statusCode:
          type: integer
          example: 200
        success:
          type: boolean
          example: true
    internal_handlers.KYCUpstreamMessage:
      type: object
      properties:
        message:
          type: string
          example: Invalid BVN or BVN does not exist
    internal_handlers.KYCBVNBasicRecord:
      type: object
      properties:
        bvn:
          type: string
          example: '22222222222'
        dateOfBirth:
          type: string
          example: '1990-01-01'
        firstName:
          type: string
          example: JOHN
        gender:
          type: string
          example: Male
        image:
          description: >-
            Base64-encoded JPEG passport photograph of the BVN holder, returned
            on

            every successful lookup. Typically ~18KB of characters and the
            dominant

            contributor to response size. This is biometric personal data — do
            not

            persist it unless you have a lawful basis to.
          type: string
        lastName:
          type: string
          example: DOE
        middleName:
          type: string
          example: ADE
        phoneNumber1:
          description: >-
            Primary phone number on the BVN record. Note the trailing "1" —
            there is

            no field named `phoneNumber`.
          type: string
          example: '08012345678'
        phoneNumber2:
          description: Secondary phone number. Frequently an empty string.
          type: string
          example: ''
  securitySchemes:
    ApiKeyAuth:
      description: >-
        Server-to-server auth. Send your API key in the "X-API-Key" header and
        your API secret in the "X-API-Secret" header.
      type: apiKey
      name: X-API-Key
      in: header

````