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
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
Agreement objects attached to this group, newest first. There are no sort or filter parameters
Show Agreement Fields
Show Agreement Fields
string
Agreement identifier (starts with
agr_). Use it in Get Agreement Content and Submit Agreement Actions.string
Always returns
"agreement"string
Title of the agreement, for example
Virtual Account Terms of Servicestring
Longer description of what is being agreed, or
nullstring
Version of the agreement, or
nullstring
Locale the agreement is written in, for example
en-GB, or nullboolean
Whether
reject is a permitted action. When false, the agreement can only be accepted. Rejecting it returns 409.string
Path of Get Agreement Content for this agreement, relative to the API host. Call it to list the terms to show before accepting.
string
Agreement status:
pending, accepted or rejected. pending is the only status that can be acted on.string
ISO 8601 timestamp when the agreement was accepted or rejected, or
null while it is pendingstring
ISO 8601 timestamp after which the agreement can no longer be acted on, or
null when it does not expirestring
ISO 8601 timestamp when created
string
ISO 8601 timestamp when last updated
string
Actor 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 refreshstring
Actor that last updated the agreement, 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/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
}