📚 Resources
🔍 Account Lookup

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

FieldTypeRequiredDescription
account_numberstringYesThe bank account number to verify
bank_idstringYesThe bank code or ID (can be obtained from the Banks API)

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

FieldTypeDescription
account_namestringThe name of the account holder as registered with the bank

Error Responses

Status CodeDescription
400Invalid request parameters (missing or invalid account_number or bank_id)
401Unauthorized - Invalid or missing JWT token
404Account not found or invalid account number/bank combination
500Internal server error

Example: cURL

# Lookup account details
curl -X POST /api/v1/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.1
Host: api.sznd.app
Authorization: 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

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)
  • Create Beneficiary - Create a beneficiary after verifying account details
  • Create Quote - 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💳 Cards