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

# Name Lookup

> Verify the recipient account name before initiating a disbursement.

# Name Lookup

The Name Lookup API allows you to verify the recipient's account name before creating a disbursement.

SplashPay supports name lookup for the following disbursement channels:

* **Mobile Money**
* **Bank Transfer**
* **Selcom Pesa**

Using this endpoint helps reduce failed transfers caused by incorrect account numbers or bank codes.

> **Tip**
> Always perform a name lookup before initiating a disbursement to allow the recipient to confirm the account details.

***

## Endpoint

```http theme={null}
POST /disbursements/name-lookup
```

***

## Authentication

Every request must include your API credentials.

| Header       | Required | Description         |
| ------------ | :------: | ------------------- |
| X-API-KEY    |     ✅    | Merchant API Key    |
| X-API-SECRET |     ✅    | Merchant API Secret |
| Content-Type |     ✅    | application/json    |

***

## Supported Channels

| Channel        | Description                           | Requires Bank Code |
| -------------- | ------------------------------------- | :----------------: |
| `MOBILE_MONEY` | Lookup a Mobile Money subscriber name |          ❌         |
| `BANK`         | Lookup a bank account holder          |          ✅         |
| `SELCOMPESA`   | Lookup a Selcom Pesa account          |          ❌         |

***

## Request Parameters

| Field           | Type   |   Required  | Description                                                               |
| --------------- | ------ | :---------: | ------------------------------------------------------------------------- |
| channel         | string |      ✅      | `MOBILE_MONEY`, `BANK`, or `SELCOMPESA`                                   |
| account\_number | string |      ✅      | Mobile number, bank account number, or Selcom Pesa account number         |
| bank\_code      | string | Conditional | Required only when `channel` is `BANK`. Use the supported bank shortcode. |

***

## Example Requests

<Tabs>
  <Tab title="Mobile Money">
    ```json theme={null}
    {
        "channel": "MOBILE_MONEY",
        "account_number": "255717879919"
    }
    ```
  </Tab>

  <Tab title="Bank">
    ```json theme={null}
    {
        "channel": "BANK",
        "account_number": "015123456789",
        "bank_code": "NMB"
    }
    ```
  </Tab>

  <Tab title="Selcom Pesa">
    ```json theme={null}
    {
        "channel": "SELCOMPESA",
        "account_number": "255717879919"
    }
    ```
  </Tab>
</Tabs>

***

## Example Response

```json theme={null}
{
    "status": "success",
    "code": "ACCOUNT_VERIFIED",
    "message": "Account verified successfully.",
    "data": {
        "channel": "BANK",
        "account_number": "015123456789",
        "account_name": "MEDSON NAFTALI",
        "bank_code": "NMB",
        "bank_name": "National Microfinance Bank"
    },
    "meta": [],
    "request_id": "4d1e3b6d-5b1b-4b9e-9d44-53f3d876e5a8"
}
```

***

## Mobile Money Response

```json theme={null}
{
    "status": "success",
    "code": "ACCOUNT_VERIFIED",
    "message": "Account verified successfully.",
    "data": {
        "channel": "MOBILE_MONEY",
        "account_number": "255717879919",
        "account_name": "MEDSON NAFTALI",
        "network": "MPESA"
    },
    "meta": [],
    "request_id": "4d1e3b6d-5b1b-4b9e-9d44-53f3d876e5a8"
}
```

***

## Selcom Pesa Response

```json theme={null}
{
    "status": "success",
    "code": "ACCOUNT_VERIFIED",
    "message": "Account verified successfully.",
    "data": {
        "channel": "SELCOMPESA",
        "account_number": "255717879919",
        "account_name": "MEDSON NAFTALI"
    },
    "meta": [],
    "request_id": "4d1e3b6d-5b1b-4b9e-9d44-53f3d876e5a8"
}
```

***

## Error Responses

### Invalid Bank Code

```json theme={null}
{
    "status": "error",
    "code": "INVALID_BANK_CODE",
    "message": "The supplied bank code is not supported."
}
```

### Account Not Found

```json theme={null}
{
    "status": "error",
    "code": "ACCOUNT_NOT_FOUND",
    "message": "Recipient account could not be verified."
}
```

### Invalid Channel

```json theme={null}
{
    "status": "error",
    "code": "INVALID_CHANNEL",
    "message": "Unsupported disbursement channel."
}
```

***

## Supported Bank Codes

For **BANK** lookups, use the bank shortcode.

| Bank                     | Code                                                                              |
| ------------------------ | --------------------------------------------------------------------------------- |
| NMB Bank                 | `NMB`                                                                             |
| CRDB Bank                | `CRDBBANK`                                                                        |
| NBC Bank                 | `NBC`                                                                             |
| Stanbic Bank             | `STANBIC`                                                                         |
| NCBA Bank                | `NCBA`                                                                            |
| Absa Bank                | `ABSA`                                                                            |
| Exim Bank                | `EXIMBANK`                                                                        |
| Equity Bank              | `EQUITYBANK`                                                                      |
| KCB Bank                 | `KCB`                                                                             |
| Tanzania Commercial Bank | `TCB`                                                                             |
| ...                      | Refer to the complete **Supported Banks** section in the Bank Disbursement guide. |

***

## Best Practices

<Steps>
  <Step title="Verify before sending">
    Perform a name lookup immediately before initiating a disbursement to reduce failed transfers.
  </Step>

  <Step title="Display the account name">
    Show the verified account name to the customer and request confirmation before submitting the transfer.
  </Step>

  <Step title="Validate bank codes">
    When using the **BANK** channel, ensure the correct bank shortcode is supplied.
  </Step>

  <Step title="Cache cautiously">
    Recipient names may change over time. Avoid caching lookup results for extended periods and perform a fresh lookup for each new transfer.
  </Step>
</Steps>

***

## Related Guides

<CardGroup cols={3}>
  <Card title="Mobile Money Disbursement" href="/disbursements/mobile-money" icon="smartphone">
    Send funds to Mobile Money wallets.
  </Card>

  <Card title="Bank Disbursement" href="/disbursements/bank" icon="building-bank">
    Transfer funds directly to bank accounts.
  </Card>

  <Card title="Selcom Pesa" href="/disbursements/selcompesa" icon="wallet">
    Transfer funds to Selcom Pesa accounts.
  </Card>
</CardGroup>