> ## 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 by phone number

> Resolves and verifies a BVN from a phone number.



## OpenAPI

````yaml /openapi.json post /kyc/identity/bvn/with-phone
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/with-phone:
    post:
      tags:
        - KYC
      summary: Verify BVN by phone number
      description: Resolves and verifies a BVN from a phone number.
      requestBody:
        $ref: '#/components/requestBodies/internal_handlers.KYCPhoneRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/internal_handlers.KYCVerificationResponse'
        '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.KYCPhoneRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/internal_handlers.KYCPhoneRequest'
      description: Phone number
      required: true
  schemas:
    internal_handlers.KYCVerificationResponse:
      type: object
      properties:
        data:
          type: object
          additionalProperties: true
        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.KYCPhoneRequest:
      type: object
      required:
        - phoneNumber
      properties:
        phoneNumber:
          type: string
          example: '08012345678'
    internal_handlers.KYCUpstreamMessage:
      type: object
      properties:
        message:
          type: string
          example: Invalid BVN or BVN does not exist
  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

````