List Documents
curl --request GET \
--url https://api.hopnow.io/v1/accounts/{account_id}/virtual-account-groups/{group_id}/documents \
--header 'X-API-Key: <api-key>'import requests
url = "https://api.hopnow.io/v1/accounts/{account_id}/virtual-account-groups/{group_id}/documents"
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/{group_id}/documents', 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/{group_id}/documents",
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/{group_id}/documents"
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/{group_id}/documents")
.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/{group_id}/documents")
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>",
"virtual_account_group_id": "<string>",
"requirement_key": "<string>",
"type": "<string>",
"side": "<string>",
"file_name": "<string>",
"content_type": "<string>",
"size_bytes": 123,
"submission_status": "<string>",
"country_code": "<string>",
"created": "<string>",
"updated": "<string>",
"created_by": "<string>",
"updated_by": "<string>"
}
],
"page": 123,
"size": 123,
"total": 123,
"pages": 123
}Virtual Account Groups
List Documents
List the evidence linked to a virtual account group and whether each file reached the provider
GET
/
v1
/
accounts
/
{account_id}
/
virtual-account-groups
/
{group_id}
/
documents
List Documents
curl --request GET \
--url https://api.hopnow.io/v1/accounts/{account_id}/virtual-account-groups/{group_id}/documents \
--header 'X-API-Key: <api-key>'import requests
url = "https://api.hopnow.io/v1/accounts/{account_id}/virtual-account-groups/{group_id}/documents"
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/{group_id}/documents', 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/{group_id}/documents",
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/{group_id}/documents"
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/{group_id}/documents")
.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/{group_id}/documents")
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>",
"virtual_account_group_id": "<string>",
"requirement_key": "<string>",
"type": "<string>",
"side": "<string>",
"file_name": "<string>",
"content_type": "<string>",
"size_bytes": 123,
"submission_status": "<string>",
"country_code": "<string>",
"created": "<string>",
"updated": "<string>",
"created_by": "<string>",
"updated_by": "<string>"
}
],
"page": 123,
"size": 123,
"total": 123,
"pages": 123
}This endpoint works on any account you own. Create Virtual Account Group covers who can open a group and what the account needs first.
Returns the evidence linked to this group, newest first. Use it to see what has already been supplied against the group’s requirements and, through
submission_status, whether each file reached the provider: a file that failed on the way out still appears here.
Items come from Upload Document, and each one’s requirement_key points back at the requirement it satisfies in Get Virtual Account Group, which remains the authority on what is still outstanding. Evidence imported by the provider outside this API is listed too, with requirement_key set to null.
Requires an API key with read access on the virtual_accounts scope.
Path Parameters
string
required
The account’s external ID (starts with
acct_)string
required
The virtual account group’s external ID (starts with
vag_). It must belong to the account in the path.Query Parameters
integer
default:"1"
Page number (minimum 1)
integer
default:"10"
Items per page (1-100)
Response
array
Document objects linked to this group, newest first. There are no sort or filter parameters
Show Document Fields
Show Document Fields
string
Document identifier (starts with
doc_). Evidence is stored at account level, so the same document id can appear under more than one group.string
Always returns
"virtual_account_group_document"string
Account the evidence belongs to (starts with
acct_)string
Virtual account group the evidence is linked to (starts with
vag_)string
Requirement this evidence satisfies, or
null for evidence the provider imported outside this APIstring
Document type, for example
passport or certificate_of_incorporation. See Upload Document for the full set.string
front or back for a two-sided identity document, otherwise nullstring
Stored file name, or
nullstring
Media type of the stored file:
application/pdf, image/jpeg or image/pnginteger
Size of the file in bytes
string
Delivery state towards the provider:
submitted once the provider acknowledged it, failed when the last delivery attempt was rejected, pending while it is on its way, and unknown for links created before delivery was tracked, including provider-imported evidence. Re-drive a failed file by uploading it again.string
ISO 3166-1 alpha-2 country of issue, or
nullstring
ISO 8601 timestamp when created
string
ISO 8601 timestamp when last updated
string
Actor that uploaded the document: the API key id (starts with
ak_), or null for provider-imported evidencestring
Actor that last updated the document, 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 | group_id is unknown or belongs to another account |
422 | VALIDATION_ERROR | page or size is out of range |
Request Example
curl "https://api.hopnow.io/v1/accounts/acct_ka44qsvpo8q3wtzuwfqf0h6u/virtual-account-groups/vag_7m2k9x4c1b6v3n8q5z0j2p7t/documents?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": "doc_xw9rlpdt0bcr5u4f9n095lf4",
"object": "virtual_account_group_document",
"account_id": "acct_ka44qsvpo8q3wtzuwfqf0h6u",
"virtual_account_group_id": "vag_7m2k9x4c1b6v3n8q5z0j2p7t",
"requirement_key": "req_9c1f4a7b2e06d38a5f4c1b72",
"type": "passport",
"side": null,
"file_name": "passport.pdf",
"content_type": "application/pdf",
"size_bytes": 248312,
"submission_status": "submitted",
"country_code": "GB",
"created": "2026-01-16T09:20:00Z",
"updated": "2026-01-16T09:20:00Z",
"created_by": "ak_3f7k9m2p5r8t1v4x6z0b3n5q",
"updated_by": null
},
{
"id": "doc_zc8ierkl3h51fun10108m4zd",
"object": "virtual_account_group_document",
"account_id": "acct_ka44qsvpo8q3wtzuwfqf0h6u",
"virtual_account_group_id": "vag_7m2k9x4c1b6v3n8q5z0j2p7t",
"requirement_key": "req_2b7e1d4a9c03f68b5e1a7c94",
"type": "national_id",
"side": "front",
"file_name": "director-id-front.png",
"content_type": "image/png",
"size_bytes": 1048576,
"submission_status": "failed",
"country_code": "GB",
"created": "2026-01-16T09:14:00Z",
"updated": "2026-01-16T09:14:00Z",
"created_by": "ak_3f7k9m2p5r8t1v4x6z0b3n5q",
"updated_by": null
}
],
"page": 1,
"size": 10,
"total": 2,
"pages": 1
}