Get All Sub-Accounts (New)

Overview

Retrieve all sub-accounts under a parent account, discover downstream customer identifiers, and use them for onboarding, wallet, and scoped platform operations.

This endpoint supports filtering by search text (partial company name matching), explicit arrays of company references, internal system IDs, and client external IDs, along with pagination controls (limit, skip) and sorting (orderBy).

Resource Access

• HTTP Method: POST
• Endpoint: /banking/ibans/v2/sub-accounts/list
• Authentication: Bearer token required (Authorization: Bearer {access_token})

Request Headers

Header	Value	Required	Description
Accept	application/json	Yes	Content type for response
Authorization	Bearer {access_token}	Yes	Bearer token for authentication
Content-Type	application/json	Yes	Request body content type
x-api-key	string	No	Optional API key

Query Parameters

Parameter	Type	Required	Description
limit	integer	No	Maximum number of records to return (1-100, default: 20).
skip	integer	No	Number of records to skip before collecting results (default: 0).
orderBy	string	No	Ordering by creation timestamp: createdAtAsc or createdAtDesc (default).

Request Body

{
  "searchText": "Acme",
  "companyReferences": [
    "CA-15092026-001"
  ],
  "ids": [
    "comp_982341"
  ],
  "externalIds": [
    "ext_acme_001"
  ]
}

Request Fields

Field	Type	Required	Description
searchText	string	No	Substring to search sub-accounts by registered company name.
companyReferences	array of strings	No	List of specific company reference codes to match.
ids	array of strings	No	List of specific system company IDs to filter by.
externalIds	array of strings	No	List of internal client external IDs to filter by.

Response

Success Response (200 OK)

{
  "totalCount": 1,
  "items": [
    {
      "id": "comp_982341",
      "externalId": "ext_acme_001",
      "parentCompanyId": "comp_100201",
      "name": "Acme Innovations Ltd",
      "country": "United Kingdom",
      "category": "Technology",
      "subCategory": "Software Development and IT Services",
      "identificationNumber": "12345678",
      "taxIdOrEin": "GB987654321",
      "accountType": "SUB_CLIENT",
      "companyReference": "CA-15092026-001",
      "companyStatus": "CREATED",
      "linkedStatus": "ACCEPTED",
      "linkedAt": "2026-09-15T10:00:00Z",
      "createdAt": "2026-09-15T10:00:00Z",
      "updatedAt": "2026-09-15T10:00:00Z"
    }
  ]
}

Response Fields

Field	Type	Description
totalCount	number	Total number of sub-accounts matching the filter query across all pages.
items	array	Array of matching sub-account objects.
items[].id	string	Unique system identifier for the sub-account.
items[].name	string	Company legal name.
items[].companyReference	string	Reference code for customer identification.
items[].companyStatus	string	Verification status (CREATED, APPROVED, REJECTED).
items[].linkedStatus	string	Parent-child linkage status (ACCEPTED, PENDING, REJECTED).
items[].createdAt	string (ISO Date)	Creation timestamp.

Error Responses

• 400 Bad Request: Invalid query parameters or malformed JSON payload.
• 401 Unauthorized: Missing or expired access token.
• 403 Forbidden: Access denied to parent organization sub-accounts.
• 500 Internal Server Error: Internal platform error.

Code Examples

cURL

curl -X POST "https://api.ahrvo.network/banking/ibans/v2/sub-accounts/list?limit=20&skip=0&orderBy=createdAtDesc" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "searchText": "Acme"
  }'

Python

import requests

url = "https://api.ahrvo.network/banking/ibans/v2/sub-accounts/list"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json",
    "Accept": "application/json"
}
params = {
    "limit": 20,
    "skip": 0,
    "orderBy": "createdAtDesc"
}
payload = {
    "searchText": "Acme"
}

response = requests.post(url, headers=headers, params=params, json=payload)
data = response.json()
print("Total Matching Sub-Accounts:", data.get("totalCount"))
for item in data.get("items", []):
    print(f"- {item['name']} (ID: {item['id']}, Ref: {item['companyReference']})")

JavaScript / Node.js

const response = await fetch("https://api.ahrvo.network/banking/ibans/v2/sub-accounts/list?limit=20&skip=0&orderBy=createdAtDesc", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json",
    "Accept": "application/json"
  },
  body: JSON.stringify({
    searchText: "Acme"
  })
});

const result = await response.json();
console.log(`Found ${result.totalCount} sub-accounts:`);
result.items?.forEach(item => {
  console.log(`- ${item.name} (${item.id}) [${item.companyStatus}]`);
});

Interactive API Explorer