List Agreements
curl --request GET \
--url https://api.hopnow.io/v1/accounts/{account_id}/virtual-account-groups/{group_id}/agreements \
--header 'X-API-Key: <api-key>'import requests
url = "https://api.hopnow.io/v1/accounts/{account_id}/virtual-account-groups/{group_id}/agreements"
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}/agreements', 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}/agreements",
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}/agreements"
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}/agreements")
.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}/agreements")
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>",
"title": "<string>",
"description": "<string>",
"version": "<string>",
"locale": "<string>",
"declinable": true,
"content_url": "<string>",
"status": "<string>",
"responded_at": "<string>",
"expires_at": "<string>",
"created": "<string>",
"updated": "<string>",
"created_by": "<string>",
"updated_by": "<string>"
}
],
"page": 123,
"size": 123,
"total": 123,
"pages": 123
}Virtual Account Groups
List Agreements
List the provider agreements attached to a virtual account group and where each one stands
GET
/
v1
/
accounts
/
{account_id}
/
virtual-account-groups
/
{group_id}
/
agreements
List Agreements
curl --request GET \
--url https://api.hopnow.io/v1/accounts/{account_id}/virtual-account-groups/{group_id}/agreements \
--header 'X-API-Key: <api-key>'import requests
url = "https://api.hopnow.io/v1/accounts/{account_id}/virtual-account-groups/{group_id}/agreements"
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}/agreements', 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}/agreements",
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}/agreements"
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}/agreements")
.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}/agreements")
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>",
"title": "<string>",
"description": "<string>",
"version": "<string>",
"locale": "<string>",
"declinable": true,
"content_url": "<string>",
"status": "<string>",
"responded_at": "<string>",
"expires_at": "<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.
Opening a group with Create Virtual Account Group starts an onboarding that asks the account for two kinds of input: evidence, uploaded with Upload Document, and agreements, the terms the account must accept before the group can be enabled.
This endpoint returns the agreements currently attached to the group, newest first.
status reflects the provider’s record.
Read the terms behind an agreement with Get Agreement Content, and accept or reject it with Submit Agreement Actions. The outstanding requirements and the group’s onboarding status come from Get Virtual Account Group; once the group is enabled you can create virtual accounts under it.
Requires an API key with read access on the virtual_accounts scope.
Path Parameters
The virtual account group’s external ID (starts with
vag_). It must belong to the account in the path.Query Parameters
Response
Agreement objects attached to this group, newest first. There are no sort or filter parameters
Show Agreement Fields
Show Agreement Fields
Agreement identifier (starts with
agr_). Use it in Get Agreement Content and Submit Agreement Actions.Whether
reject is a permitted action. When false, the agreement can only be accepted. Rejecting it returns 409.Path of Get Agreement Content for this agreement, relative to the API host. Call it to list the terms to show before accepting.
Agreement status:
pending, accepted or rejected. pending is the only status that can be acted on.ISO 8601 timestamp after which the agreement can no longer be acted on, or
null when it does not expireActor whose call created the agreement record: the API key id (starts with
ak_) when opening the group brought it in, or null when Hop picked it up during a background refreshErrors
| 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/agreements?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": "agr_3f8k1m5p9r2t6v4x7z0b3n5q",
"object": "agreement",
"title": "Virtual Account Terms of Service",
"description": "Terms governing virtual accounts opened under this group",
"version": "2.1",
"locale": "en-GB",
"declinable": false,
"content_url": "/v1/accounts/acct_ka44qsvpo8q3wtzuwfqf0h6u/virtual-account-groups/vag_7m2k9x4c1b6v3n8q5z0j2p7t/agreements/agr_3f8k1m5p9r2t6v4x7z0b3n5q/content",
"status": "pending",
"responded_at": null,
"expires_at": "2026-03-01T00:00:00Z",
"created": "2026-01-15T10:00:00Z",
"updated": "2026-01-15T10:00:00Z",
"created_by": null,
"updated_by": null
},
{
"id": "agr_10uu44q9ziih39vh89wbeg11",
"object": "agreement",
"title": "Data Processing Addendum",
"description": null,
"version": "1.0",
"locale": "en-GB",
"declinable": true,
"content_url": "/v1/accounts/acct_ka44qsvpo8q3wtzuwfqf0h6u/virtual-account-groups/vag_7m2k9x4c1b6v3n8q5z0j2p7t/agreements/agr_10uu44q9ziih39vh89wbeg11/content",
"status": "accepted",
"responded_at": "2026-01-16T09:12:00Z",
"expires_at": null,
"created": "2026-01-15T10:00:00Z",
"updated": "2026-01-16T09:12:00Z",
"created_by": null,
"updated_by": null
}
],
"page": 1,
"size": 10,
"total": 2,
"pages": 1
}