> ## 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 Account Groups

> Retrieve a paginated list of the virtual account groups opened for an account

Works on any account you own. [Create Virtual Account Group](/fx/api-reference/virtual-account-groups/create-group) covers who can open a group and what the account needs before onboarding can progress: an identity profile, plus an associated person marked as a signer on a business account.

Returns the groups opened for one account, newest first by creation time. There are no sort or filter parameters. You can onboard the same account for multiple group types, with one group per type.

List items are the group summary, the same shape [Create Virtual Account Group](/fx/api-reference/virtual-account-groups/create-group) returns. They carry **no** `requirements` and no `agreements` summary: read [Get Virtual Account Group](/fx/api-reference/virtual-account-groups/get-group) for the outstanding onboarding actions on a group.

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

## Path Parameters

<ParamField path="account_id" type="string" required>
  The account's external ID (starts with `acct_`). It must belong to your customer: your own account, one of your end-customer accounts, or your fee-collection account.
</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 group objects, newest first

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

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

    <ResponseField name="account_id" type="string">
      Account the group belongs to (starts with `acct_`)
    </ResponseField>

    <ResponseField name="type" type="string">
      Group type, for example `business_virtual_accounts`. See [List Group Types](/fx/api-reference/virtual-account-groups/list-group-types).
    </ResponseField>

    <ResponseField name="status" type="string">
      Activation state, controlled by Hop: `pending`, `enabled` or `disabled`. Only an `enabled` group whose `onboarding_status` is `approved` can back virtual accounts.
    </ResponseField>

    <ResponseField name="onboarding_status" type="string">
      KYC/KYB progress: `action_needed`, `under_review`, `approved`, `rejected`, `suspended` or `closed`. See [Create Virtual Account Group](/fx/api-reference/virtual-account-groups/create-group) for what each means and how they transition.
    </ResponseField>

    <ResponseField name="enabled_at" type="string">
      ISO 8601 timestamp when Hop first enabled the group, or `null`
    </ResponseField>

    <ResponseField name="suspended_at" type="string">
      ISO 8601 timestamp when onboarding most recently became `suspended`, or `null`
    </ResponseField>

    <ResponseField name="closed_at" type="string">
      ISO 8601 timestamp when onboarding was closed, or `null`
    </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 group: 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 group, 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` | `account_id` is unknown or belongs to another customer |
| `422` | `VALIDATION_ERROR` | `page` is below 1, or `size` is outside 1-100 |

## Request Example

```bash theme={null}
curl "https://api.hopnow.io/v1/accounts/acct_ka44qsvpo8q3wtzuwfqf0h6u/virtual-account-groups?page=1&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": "vag_7m2k9x4c1b6v3n8q5z0j2p7t",
      "object": "virtual_account_group",
      "account_id": "acct_ka44qsvpo8q3wtzuwfqf0h6u",
      "type": "business_virtual_accounts",
      "status": "enabled",
      "onboarding_status": "approved",
      "enabled_at": "2026-01-19T09:30:00Z",
      "suspended_at": null,
      "closed_at": null,
      "created": "2026-01-15T10:00:00Z",
      "updated": "2026-01-19T09:30:00Z",
      "created_by": "ak_3f7k9m2p5r8t1v4x6z0b3n5q",
      "updated_by": null
    }
  ],
  "page": 1,
  "size": 10,
  "total": 1,
  "pages": 1
}
```