> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.hopnow.io/llms.txt
> Use this file to discover all available pages before exploring further.

# List Virtual Accounts

> Retrieve a paginated list of the virtual accounts in one virtual account group

Returns the virtual accounts belonging to one [virtual account group](/fx/api-reference/virtual-account-groups/create-group), newest first. There are no sort parameters.

List items are the same shape as [Get Virtual Account](/fx/api-reference/virtual-accounts/get-virtual-account): every field, including the full bank details, is present on each row. There are no `status` or `currency` filters, so a group with several currencies returns them all and you filter client-side. Virtual accounts in another group on the same account are not included: list each group separately.

Requires an API key with `read` access on the `virtual_accounts` scope.

There is no disable or delete endpoint for virtual accounts on this API. A virtual account cannot be closed, frozen or renamed through the client API. `frozen` and `disabled` are set by Hop, so a virtual account you created stays in this list for the life of the account. Set a durable `label` when you create the virtual account: neither the label nor the account can be changed afterwards.

## Path Parameters

<ParamField path="account_id" type="string" required>
  The account's external ID (starts with `acct_`)
</ParamField>

<ParamField path="group_id" type="string" required>
  The virtual account group's external ID (starts with `vag_`). An unknown group, or one belonging to another account, returns `404`, not an empty page.
</ParamField>

## Query Parameters

<ParamField query="page" type="integer" default="1">
  Page number (minimum 1)
</ParamField>

<ParamField query="size" type="integer" default="10">
  Items per page (1-100)
</ParamField>

## Response

<ResponseField name="items" type="array">
  Virtual account objects, newest first

  <Expandable title="Virtual Account Fields">
    <ResponseField name="id" type="string">
      Virtual account identifier (starts with `va_`)
    </ResponseField>

    <ResponseField name="object" type="string">
      Always returns `"virtual_account"`
    </ResponseField>

    <ResponseField name="account_id" type="string">
      Account ID (starts with `acct_`). Rows do not repeat `group_id`. Every item belongs to the group in the path.
    </ResponseField>

    <ResponseField name="currency" type="string">
      Currency code of the virtual account
    </ResponseField>

    <ResponseField name="status" type="string">
      Virtual account status: `pending`, `active`, `frozen` or `disabled`. Only an `active` virtual account is payable and usable as a payout funding source or transfer leg.
    </ResponseField>

    <ResponseField name="label" type="string">
      Label, or `null`
    </ResponseField>

    <ResponseField name="balances" type="object">
      Balance buckets, each a decimal string formatted for the currency

      <Expandable title="Balance Fields">
        <ResponseField name="available" type="string">
          Balance free to spend on a payout or transfer
        </ResponseField>

        <ResponseField name="pending_payin" type="string">
          Deposits received but not yet settled
        </ResponseField>

        <ResponseField name="held_for_payout" type="string">
          Amount held for in-flight payouts
        </ResponseField>

        <ResponseField name="total" type="string">
          Total across all buckets
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="beneficiary_name" type="string">
      Account holder a payer should address the deposit to, or `null`
    </ResponseField>

    <ResponseField name="bank_name" type="string">
      Bank holding the account, or `null`
    </ResponseField>

    <ResponseField name="account_number" type="string">
      Full account number, or `null` on a `pending` row and on accounts identified by IBAN
    </ResponseField>

    <ResponseField name="account_number_last4" type="string">
      Account number masked as `****` + last 4. The IBAN is masked instead when there is no account number. `null` on a `pending` row.
    </ResponseField>

    <ResponseField name="iban" type="string">
      Full IBAN, or `null` on a `pending` row and on accounts identified by account number
    </ResponseField>

    <ResponseField name="swift_bic" type="string">
      SWIFT/BIC code, or `null`
    </ResponseField>

    <ResponseField name="routing_number" type="string">
      Routing number or sort code, or `null`
    </ResponseField>

    <ResponseField name="routing_number_type" type="string">
      What `routing_number` holds, for example `ROUTING_NUMBER` or `SORT_CODE`; `null` when there is no routing number
    </ResponseField>

    <ResponseField name="bank_address" type="object">
      Bank address for wire instructions (`address_line`, `city`, `region`, `postal_code`, `country`), or `null`
    </ResponseField>

    <ResponseField name="beneficiary_address" type="object">
      Account holder address for wire instructions, same shape as `bank_address`, or `null`
    </ResponseField>

    <ResponseField name="provisioned_at" type="string">
      ISO 8601 timestamp when the bank details became available, or `null` while `pending`
    </ResponseField>

    <ResponseField name="created" type="string">
      ISO 8601 timestamp when created
    </ResponseField>

    <ResponseField name="updated" type="string">
      ISO 8601 timestamp when last updated
    </ResponseField>

    <ResponseField name="created_by" type="string">
      Actor that created the virtual account: the API key id (starts with `ak_`) when opened through this API, otherwise the actor Hop recorded
    </ResponseField>

    <ResponseField name="updated_by" type="string">
      Actor that last updated the virtual account, or `null`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="page" type="integer">
  Current page number
</ResponseField>

<ResponseField name="size" type="integer">
  Items per page
</ResponseField>

<ResponseField name="total" type="integer">
  Total number of items
</ResponseField>

<ResponseField name="pages" type="integer">
  Total number of pages
</ResponseField>

## Errors

| Status | `code` | When |
| - | - | - |
| `404` | `RESOURCE_NOT_FOUND` | `group_id` is unknown or belongs to another account |
| `422` | `VALIDATION_ERROR` | `page` or `size` is out of range |

## Request Example

```bash theme={null}
curl "https://api.hopnow.io/v1/accounts/acct_ka44qsvpo8q3wtzuwfqf0h6u/virtual-account-groups/vag_8p2m5k9t3w6b1r4n7z0c5v3h/virtual-accounts?size=10" \
  -H "X-API-Key: your_api_key" \
  -H "X-Signature: hmac_signature" \
  -H "X-Timestamp: 1234567890" \
  -H "X-Nonce: abc123"
```

## Response Example

```json theme={null}
{
  "items": [
    {
      "id": "va_6b3n9k1q4t7w2z5m8p0r3d6f",
      "object": "virtual_account",
      "account_id": "acct_ka44qsvpo8q3wtzuwfqf0h6u",
      "currency": "EUR",
      "status": "active",
      "label": "EU Collections",
      "balances": {
        "available": "250.00",
        "pending_payin": "0.00",
        "held_for_payout": "0.00",
        "total": "250.00"
      },
      "beneficiary_name": "Acme GmbH",
      "bank_name": "Example Bank",
      "account_number": null,
      "account_number_last4": "****3000",
      "iban": "DE89370400440532013000",
      "swift_bic": "DEUTDEFFXXX",
      "routing_number": null,
      "routing_number_type": null,
      "bank_address": {
        "address_line": "1 Bank Street",
        "city": "Frankfurt",
        "region": null,
        "postal_code": "60311",
        "country": "DE"
      },
      "beneficiary_address": {
        "address_line": "22 Hauptstrasse",
        "city": "Berlin",
        "region": null,
        "postal_code": "10115",
        "country": "DE"
      },
      "provisioned_at": "2026-01-15T10:12:00Z",
      "created": "2026-01-15T10:00:00Z",
      "updated": "2026-01-15T10:12:00Z",
      "created_by": "ak_3f7k9m2p5r8t1v4x6z0b3n5q",
      "updated_by": null
    },
    {
      "id": "va_2w9e4r7t1y5u8i3o6p0a5s2d",
      "object": "virtual_account",
      "account_id": "acct_ka44qsvpo8q3wtzuwfqf0h6u",
      "currency": "USD",
      "status": "pending",
      "label": "US Collections",
      "balances": {
        "available": "0.00",
        "pending_payin": "0.00",
        "held_for_payout": "0.00",
        "total": "0.00"
      },
      "beneficiary_name": null,
      "bank_name": null,
      "account_number": null,
      "account_number_last4": null,
      "iban": null,
      "swift_bic": null,
      "routing_number": null,
      "routing_number_type": null,
      "bank_address": null,
      "beneficiary_address": null,
      "provisioned_at": null,
      "created": "2026-01-14T09:00:00Z",
      "updated": "2026-01-14T09:00:00Z",
      "created_by": "ak_3f7k9m2p5r8t1v4x6z0b3n5q",
      "updated_by": null
    }
  ],
  "page": 1,
  "size": 10,
  "total": 2,
  "pages": 1
}
```