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

# Name Lookup

> Checks the phone number and network already on file for the given customer_key against whichever provider (pawaPay or Onafriq) would actually handle a payout to them, reducing the risk of sending funds to the wrong recipient.

Before disbursing a payout, confirm the recipient's name matches what the receiving mobile money provider has on file for that phone number — reduces the risk of sending funds to the wrong person.

The phone number and network checked are always the ones already on file for the `customer_key` you pass — you can't look up an arbitrary phone number, only an existing mobile money customer.

<Note>
  This feature is gated per integrator. If your account doesn't have it enabled, contact [sales@kotanipay.com](mailto:sales@kotanipay.com) to request access.
</Note>

<Note>
  Match scoring (`matchScore`) is only available for some payout corridors — it may be absent even on a `MATCHED` result.
</Note>


## OpenAPI

````yaml POST /api/v3/name-lookup
openapi: 3.0.0
info:
  title: KOTANI PAY API PLATFORM
  description: ''
  version: '3.0'
  contact: {}
servers:
  - url: https://sandbox-api.kotanipay.io
    description: Sandbox
security: []
tags: []
paths:
  /api/v3/name-lookup:
    post:
      tags:
        - NAME LOOKUP
      summary: Validate a phone number against a customer name before payout
      description: >-
        Checks the phone number and network already on file for the given
        customer_key against whichever provider (pawaPay or Onafriq) would
        actually handle a payout to them, reducing the risk of sending funds to
        the wrong recipient.
      operationId: NameLookupController_lookup_api/v3
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NameLookupRequestDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Name lookup completed.
                  data:
                    $ref: '#/components/schemas/NameLookupResponseDto'
                    type: object
        '400':
          description: ''
          content:
            application/json:
              schema:
                properties:
                  success:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: Bad Request
                  data:
                    type: object
                    example: {}
        '401':
          description: ''
          content:
            application/json:
              schema:
                properties:
                  success:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: Invalid API Key
                  data:
                    type: object
                    example: {}
      security:
        - JWT: []
components:
  schemas:
    NameLookupRequestDto:
      type: object
      properties:
        walletId:
          type: string
          description: >-
            The fiat wallet the payout would be debited from — used to resolve
            which provider would actually handle it.
          example: 5f9b2c7b9c9d6b0017b4e6b1
        customer_key:
          type: string
          description: >-
            Customer key of an existing mobile-money customer. The phone number,
            network, and name validated are always the ones already on file for
            this customer — not arbitrary values — so the result reflects who
            would actually receive this payout.
          example: customer-key-123
      required:
        - walletId
        - customer_key
    NameLookupResponseDto:
      type: object
      properties:
        status:
          type: string
          enum:
            - MATCHED
            - NOT_FOUND
            - UNSUPPORTED
            - TIMEOUT
            - ERROR
          description: Outcome of the lookup
        fullName:
          type: string
          description: Name on file with the mobile money provider, if resolved.
        matchScore:
          type: number
          description: >-
            Percentage match between the customer's name on file and the name on
            file for this phone number. Only populated when match scoring is
            available for this payout corridor; may be absent otherwise.
        reason:
          type: string
          description: >-
            Human-readable explanation, populated for UNSUPPORTED/ERROR
            outcomes.
      required:
        - status
  securitySchemes:
    JWT:
      scheme: bearer
      bearerFormat: JWT
      type: http

````