Get All Beneficiaries

Overview

This service is used to get the list of all beneficiaries set for a particular user including the details such as ID, accountNumber, bankName, address, clientReference, status and other fields too.

Supports cursor/page-based pagination for high-throughput enterprise accounts.

Resource Access

• HTTP Method: GET
• Endpoint: /profile/v2.1/beneficiaries
• Authentication: Bearer token required (Authorization: Bearer {access_token})

Query Parameters

Parameter	Type	Required	Description
customPageSize	number	No	Specifies the number of records to be returned per page (default: 10).
page	number	No	Specifies the page number to be retrieved in a paginated response (default: 1).

Response

Success Response (200 OK)

{
  "success": true,
  "data": [
    {
      "id": 3997,
      "accountNumber": "2000293918130",
      "bankName": "Punjab National Bank",
      "beneficiaryAddress": "7, Bhikaji Cama Place Africa Avenue",
      "beneficiaryCity": "New Delhi",
      "beneficiaryCompanyName": "OLSEN INDUSTRIA E COMERCIO SA",
      "beneficiaryCountryCode": "IN",
      "beneficiaryEntityType": "company",
      "currency": "INR",
      "clientReference": "Test Beneficiary For Company",
      "status": "approved"
    },
    {
      "id": 3994,
      "accountNumber": "2000293918130",
      "bankName": "Punjab National Bank",
      "beneficiaryFirstName": "Jon",
      "beneficiaryLastName": "Doe",
      "beneficiaryCountryCode": "IN",
      "beneficiaryEntityType": "individual",
      "currency": "INR",
      "status": "approved"
    }
  ],
  "metadata": {
    "total": 26,
    "currentPage": 1,
    "pageSize": 10
  }
}

Response Fields

Field	Type	Description
success	boolean	Boolean flag indicating whether the query completed successfully.
data	array	Array of beneficiary objects matching the pagination query.
data[].id	number	Unique beneficiary identifier.
data[].accountNumber	string	Bank account number or IBAN.
data[].bankName	string	Name of the recipient bank.
data[].status	string	Approval and readiness status (approved, pending verification, rejected).
metadata.total	number	Total count of beneficiaries registered under your account.
metadata.currentPage	number	Current page index.
metadata.pageSize	number	Number of records per page.

Error Responses

• 400 Bad Request: Invalid pagination parameters.
• 401 Unauthorized: Missing or expired authentication token.
• 403 Forbidden: Access restricted.
• 500 Internal Server Error: Internal platform error.

Code Examples

cURL

curl -X GET "https://api.ahrvo.network/banking/ibans/v2/profile/v2.1/beneficiaries?customPageSize=10&page=1" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Python

import requests

url = "https://api.ahrvo.network/banking/ibans/v2/profile/v2.1/beneficiaries"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Accept": "application/json"
}
params = {
    "customPageSize": 10,
    "page": 1
}

response = requests.get(url, headers=headers, params=params)
data = response.json()
print(f"Total beneficiaries: {data.get('metadata', {}).get('total')}")
for bene in data.get("data", []):
    print(f"- ID {bene['id']}: {bene.get('beneficiaryFirstName') or bene.get('beneficiaryCompanyName')} ({bene['currency']})")

JavaScript / Node.js

const response = await fetch("https://api.ahrvo.network/banking/ibans/v2/profile/v2.1/beneficiaries?customPageSize=10&page=1", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Accept": "application/json"
  }
});

const result = await response.json();
console.log(`Retrieved ${result.data?.length} of ${result.metadata?.total} beneficiaries`);

Interactive API Explorer