Account Lookup API

The Account Lookup API allows you to verify bank account details and retrieve the account holder's name before creating beneficiaries or initiating transfers. This helps ensure accuracy and reduces failed transactions.

Lookup Bank Account

Verify if a bank account exists and retrieve the account holder's name. This endpoint is essential for validating account information before creating beneficiaries or processing payments.

Endpoint

POST /api/v1/client/banks/account/lookup

Authentication

This endpoint requires JWT authentication. Include your access token in the Authorization header:

Authorization: Bearer <your-access-token>

Request Body

Request Example

{  "account_number": "0123456789",  "bank_id": "058"}

Success Response (200 OK)

Returns the account holder's name if the account exists:

{  "account_name": "John Doe"}

Response Fields

Error Responses

Example: cURL

# Lookup account detailscurl -X POST https://api.sznd.app/api/v1/client/banks/account/lookup \  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \  -H "Content-Type: application/json" \  -d '{    "account_number": "0123456789",    "bank_id": "058"  }'

Example: HTTP Request

POST /api/v1/client/banks/account/lookup HTTP/1.1Host: api.sznd.appAuthorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...Content-Type: application/json
{  "account_number": "0123456789",  "bank_id": "058"}

Example: JavaScript (Fetch)

const response = await fetch('https://api.sznd.app/api/v1/client/banks/account/lookup', {  method: 'POST',  headers: {    'Authorization': `Bearer ${accessToken}`,    'Content-Type': 'application/json'  },  body: JSON.stringify({    account_number: '0123456789',    bank_id: '058'  })});
const data = await response.json();console.log('Account Name:', data.account_name);

Use Cases

1. Pre-validation - Verify account details before creating beneficiaries to ensure accuracy
2. User Experience - Display the account holder's name to users for confirmation before submitting transfers
3. Error Prevention - Catch invalid account numbers early to avoid failed transactions
4. Compliance - Verify account ownership before processing sensitive financial transactions

Best Practices

1. Cache Results - Account names don't change frequently; consider caching results for a short period
2. Validate Input - Ensure account_number and bank_id are valid before making the request
3. Handle Errors Gracefully - Provide clear error messages when accounts are not found
4. Use Bank IDs - Prefer using bank id from the Banks API over bank codes for better reliability
5. Verify Before Creating - Always verify account details before creating beneficiaries or initiating transfers

Supported Countries

Currently, account lookup is supported for:

• Nigeria (NGN) - All major Nigerian banks

Sample NGN test account (staging)

For testing in non‑production environments, you can use the following sample NGN bank account (OPay, code from Banks API) to verify your integration end‑to‑end:

{  "account_number": "8080808080",  "bank_id": "100004"}

Use bank code 100004 (OPay). This sample request returns an account_name value of "OPAY Test Account", which is convenient for automated tests and manual QA flows.

Note: Support for additional countries may be added in the future. Contact support for more information.

Related Endpoints

• Banks API - Get list of banks for a country (to obtain bank_id)
• Beneficiaries - Create a beneficiary after verifying account details
• Create and accept quotes - Create a quote for a transfer after beneficiary verification

Next Steps

After verifying an account:

1. Create Beneficiary - Use the verified account details to create a beneficiary record
2. Initiate Transfer - Create a quote and process the transfer with confidence
3. Display Confirmation - Show the account holder's name to users for final confirmation

For more information, see:

• Beneficiaries - How to create and manage beneficiaries
• Banks API - Get list of banks for a country