Get all Beneficiaries (Legacy)

Overview

This service is used to retrieve the list of all beneficiaries configured for a particular user or company, including IDs, account numbers, bank names, addresses, client references, and approval statuses.

Resource Access

• HTTP Method: GET
• Endpoint: /profile/v2.1/beneficiaries
• Authentication: Bearer token required

Request Headers

Header	Value	Required	Description
Accept	application/json	Yes	Content type for the response
Authorization	Bearer {access_token}	Yes	Bearer token for authentication
x-api-key	string	No	API key for additional authentication

Query Parameters

Parameter	Type	Required	Description
pageSize	integer	No	Number of records per page (default: 10).
page	integer	No	Page number to retrieve (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",
      "beneficiaryPostcode": "110066",
      "country": "India",
      "reference": "RP-17062022-001",
      "beneficiaryFirstName": null,
      "beneficiaryLastName": null,
      "nationalId": "PUNB0644100",
      "currency": "INR",
      "clientReference": "Test Beneficiary For Individual",
      "status": "approved"
    }
  ],
  "metadata": {
    "total": 26,
    "currentPage": 1,
    "pageSize": 10
  }
}

Response Fields

Field	Type	Description
success	boolean	Flag indicating whether list was retrieved successfully.
data	array	List of beneficiary account objects.
data[].id	number	Unique ID of the beneficiary.
data[].accountNumber	string	Bank account number.
data[].bankName	string	Bank name.
data[].status	string	Approval status.
metadata.total	number	Total count of records.
metadata.currentPage	number	Current page number.
metadata.pageSize	number	Records per page.

Error Responses

• 400 Bad Request: Invalid parameters or malformed request
• 401 Unauthorized: Missing or invalid Bearer authentication token
• 403 Forbidden: Insufficient account permissions
• 404 Not Found: Resource not found
• 500 Internal Server Error: An internal server error occurred

Code Examples

Base URL

Production: https://api.ahrvo.network
Staging:    https://gateway.ahrvo.network

cURL

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

Python

import requests

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

response = requests.get(url, params=params, headers=headers)
print(response.json())

JavaScript (Node.js)

const axios = require('axios');

const url = 'https://gateway.ahrvo.network/banking/ibans/v2/profile/v2.1/beneficiaries';
const headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
};
const params = { pageSize: 10, page: 1 };

axios.get(url, { headers, params })
  .then(response => console.log(response.data))
  .catch(error => console.error(error.response ? error.response.data : error.message));

Usage Notes

• Paginate using the page and pageSize parameters.
• Inspect status field to verify if beneficiary is approved before submitting payment requests.

Interactive API Explorer