List Beneficiaries (Atlas)

Overview

The GET /banking/ibans/v2/recipients endpoint fetches a paginated collection of beneficiaries belonging to your organization. Powerful query filters enable selecting records by approval status, target currency, account number subsets, active state, stablecoin flags, or full-text search across labels and names.

Resource Access

• HTTP Method: GET
• Endpoint: /banking/ibans/v2/recipients
• Authentication: Bearer token required

Request Headers

Header	Value	Required	Description
Authorization	Bearer {access_token}	Yes	JWT Bearer access token
Accept	application/json	Yes	Response payload format
x-api-key	string	No	Optional API key

Query Parameters

Parameter	Type	Required	Description
limit	integer	No	Maximum number of records to return (max 100, default 20).
skip	integer	No	Number of records to skip for pagination.
searchQuery	string	No	Free-text search matching beneficiary names, labels, or references.
filter	string (enum)	No	Approval status filter: approved, pending, rejected, all.
currencyId	string	No	Filter by specific currency identifier.
accountId	string	No	Filter by associated internal bank account ID.
accountNumbers	string	No	Comma-separated list of account numbers.
accountIds	string	No	Comma-separated list of numeric account IDs (^[0-9,]+$).
stablecoin	boolean/string	No	Filter to return only stablecoin recipient records.
isAccountActive	boolean	No	Filter by active (true) or inactive (false) state.
isSelfAccount	string	No	Filter by own accounts vs third-party accounts.
companyId	string	No	Filter by company identifier.
excludeCompanyId	number	No	Exclude records linked to this company ID.
excludeReference	string	No	Exclude beneficiaries matching this reference prefix.
adminVerified	string	No	Filter by compliance administrative verification flag.
needsUpdate	boolean	No	Filter records flagged for remediation or info updates.

Response

Success Response (200 OK)

{
  "totalCount": 2,
  "items": [
    {
      "id": 948201,
      "companyId": 1045,
      "currencyId": 1,
      "paymentMode": "LOCAL",
      "beneficiaryType": "company",
      "companyName": "Acme Global Logistics Ltd",
      "accountNumber": "20406080",
      "bankCode": "200000",
      "bankName": "Barclays Bank UK",
      "verificationState": "approved",
      "isAccountActive": true,
      "createdAt": "2026-09-15T18:30:00.000Z"
    },
    {
      "id": 948202,
      "companyId": 1045,
      "currencyId": 4,
      "paymentMode": "STABLECOIN",
      "beneficiaryType": "company",
      "companyName": "Alpha Trading Corp",
      "accountLabel": "Alpha Treasury USDC",
      "cryptoCurrency": "USDC",
      "blockchain": "ethereum_erc20",
      "cryptoCurrencyWalletAddress": "0x71C84712F2843A1B51390467aC01C5B72803b9b3",
      "verificationState": "approved",
      "isAccountActive": true,
      "createdAt": "2026-09-15T18:32:00.000Z"
    }
  ]
}

Response Fields

Field	Type	Description
totalCount	integer	Total number of beneficiaries matching the query filters.
items	array	Array of beneficiary objects (beneficiaryClient).
items[].id	integer	Unique identifier of the beneficiary record.
items[].currencyId	integer	Currency ID supported by this beneficiary.
items[].paymentMode	string	Supported payment rail (LOCAL, INTERNATIONAL, STABLECOIN, etc.).
items[].verificationState	string	Current compliance verification status (approved, pending, rejected).
items[].isAccountActive	boolean	Whether the beneficiary is active for payout execution.

Code Examples

cURL

curl -X GET "https://gateway.ahrvo.network/banking/ibans/v2/recipients?limit=10&filter=approved&currencyId=1" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Python

import requests

url = "https://gateway.ahrvo.network/banking/ibans/v2/recipients"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Accept": "application/json"
}
params = {
    "limit": 10,
    "filter": "approved",
    "currencyId": "1"
}

response = requests.get(url, params=params, headers=headers)
data = response.json()
print("Total Beneficiaries:", data["totalCount"])
for b in data["items"]:
    print(f"ID: {b['id']} | Name: {b.get('companyName') or b.get('firstName')}")

JavaScript (Node.js)

const axios = require('axios');

const url = 'https://gateway.ahrvo.network/banking/ibans/v2/recipients';
const headers = {
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
  'Accept': 'application/json'
};

axios.get(url, {
  headers,
  params: { limit: 10, filter: 'approved', currencyId: '1' }
})
  .then(res => {
    console.log('Total Count:', res.data.totalCount);
    res.data.items.forEach(b => console.log(b.id, b.paymentMode));
  })
  .catch(err => console.error(err.response ? err.response.data : err.message));

Interactive API Explorer