List Virtual Account Groups
curl --request GET \
--url https://api.hopnow.io/v1/accounts/{account_id}/virtual-account-groups \
--header 'X-API-Key: <api-key>'import requests
url = "https://api.hopnow.io/v1/accounts/{account_id}/virtual-account-groups"
headers = {"X-API-Key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};
fetch('https://api.hopnow.io/v1/accounts/{account_id}/virtual-account-groups', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.hopnow.io/v1/accounts/{account_id}/virtual-account-groups",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.hopnow.io/v1/accounts/{account_id}/virtual-account-groups"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-API-Key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.hopnow.io/v1/accounts/{account_id}/virtual-account-groups")
.header("X-API-Key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.hopnow.io/v1/accounts/{account_id}/virtual-account-groups")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"items": [
{
"id": "<string>",
"object": "<string>",
"account_id": "<string>",
"type": "<string>",
"status": "<string>",
"onboarding_status": "<string>",
"enabled_at": "<string>",
"suspended_at": "<string>",
"closed_at": "<string>",
"created": "<string>",
"updated": "<string>",
"created_by": "<string>",
"updated_by": "<string>"
}
],
"page": 123,
"size": 123,
"total": 123,
"pages": 123
}Virtual Account Groups
List Virtual Account Groups
Retrieve a paginated list of the virtual account groups opened for an account
GET
/
v1
/
accounts
/
{account_id}
/
virtual-account-groups
List Virtual Account Groups
curl --request GET \
--url https://api.hopnow.io/v1/accounts/{account_id}/virtual-account-groups \
--header 'X-API-Key: <api-key>'import requests
url = "https://api.hopnow.io/v1/accounts/{account_id}/virtual-account-groups"
headers = {"X-API-Key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};
fetch('https://api.hopnow.io/v1/accounts/{account_id}/virtual-account-groups', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.hopnow.io/v1/accounts/{account_id}/virtual-account-groups",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.hopnow.io/v1/accounts/{account_id}/virtual-account-groups"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-API-Key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.hopnow.io/v1/accounts/{account_id}/virtual-account-groups")
.header("X-API-Key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.hopnow.io/v1/accounts/{account_id}/virtual-account-groups")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"items": [
{
"id": "<string>",
"object": "<string>",
"account_id": "<string>",
"type": "<string>",
"status": "<string>",
"onboarding_status": "<string>",
"enabled_at": "<string>",
"suspended_at": "<string>",
"closed_at": "<string>",
"created": "<string>",
"updated": "<string>",
"created_by": "<string>",
"updated_by": "<string>"
}
],
"page": 123,
"size": 123,
"total": 123,
"pages": 123
}Works on any account you own. Create Virtual Account 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. An account can hold several groups.
List items are the group summary, the same shape Create Virtual Account Group returns. They carry no
requirements and no agreements summary: read Get Virtual Account Group for the outstanding onboarding actions on a group.
Requires an API key with read access on the virtual_accounts scope.
Path Parameters
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.Query Parameters
integer
default:"1"
Page number (minimum 1)
integer
default:"10"
Items per page (1-100)
Response
array
Virtual account group objects, newest first
Show Virtual Account Group Fields
Show Virtual Account Group Fields
string
Virtual account group identifier (starts with
vag_)string
Always returns
"virtual_account_group"string
Account the group belongs to (starts with
acct_)string
Group type, for example
business_virtual_accounts. See List Group Types.string
Activation state, controlled by Hop:
pending, enabled or disabled. Only an enabled group whose onboarding_status is approved can back virtual accounts.string
KYC/KYB progress:
action_needed, under_review, approved, rejected, suspended or closed. See Create Virtual Account Group for what each means and how they transition.string
ISO 8601 timestamp when Hop first enabled the group, or
nullstring
ISO 8601 timestamp when onboarding most recently became
suspended, or nullstring
ISO 8601 timestamp when onboarding was closed, or
nullstring
ISO 8601 timestamp when created
string
ISO 8601 timestamp when last updated
string
Actor that created the group: the API key id (starts with
ak_) when opened through this API, otherwise the actor Hop recordedstring
Actor that last updated the group, or
nullinteger
Current page number
integer
Items per page
integer
Total number of items
integer
Total number of pages
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
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
{
"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
}