List Beneficiaries
curl --request GET \
--url https://api.hopnow.io/v1/accounts/{account_id}/beneficiaries \
--header 'X-API-Key: <api-key>'import requests
url = "https://api.hopnow.io/v1/accounts/{account_id}/beneficiaries"
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}/beneficiaries', 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}/beneficiaries",
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}/beneficiaries"
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}/beneficiaries")
.header("X-API-Key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.hopnow.io/v1/accounts/{account_id}/beneficiaries")
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>",
"beneficiary_type": "<string>",
"title": "<string>",
"first_name": "<string>",
"middle_name": "<string>",
"last_name": "<string>",
"display_name": "<string>",
"company_name": "<string>",
"email": "<string>",
"phone": "<string>",
"address": {},
"country_code": "<string>",
"status": "<string>",
"verified": true,
"self_owned": true,
"payout_destinations": [
{}
],
"created": "<string>",
"updated": "<string>",
"created_by": "<string>",
"updated_by": "<string>"
}
],
"page": 123,
"size": 123,
"total": 123,
"pages": 123
}Beneficiaries
List Beneficiaries
Retrieve a paginated list of beneficiaries
GET
/
v1
/
accounts
/
{account_id}
/
beneficiaries
List Beneficiaries
curl --request GET \
--url https://api.hopnow.io/v1/accounts/{account_id}/beneficiaries \
--header 'X-API-Key: <api-key>'import requests
url = "https://api.hopnow.io/v1/accounts/{account_id}/beneficiaries"
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}/beneficiaries', 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}/beneficiaries",
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}/beneficiaries"
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}/beneficiaries")
.header("X-API-Key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.hopnow.io/v1/accounts/{account_id}/beneficiaries")
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>",
"beneficiary_type": "<string>",
"title": "<string>",
"first_name": "<string>",
"middle_name": "<string>",
"last_name": "<string>",
"display_name": "<string>",
"company_name": "<string>",
"email": "<string>",
"phone": "<string>",
"address": {},
"country_code": "<string>",
"status": "<string>",
"verified": true,
"self_owned": true,
"payout_destinations": [
{}
],
"created": "<string>",
"updated": "<string>",
"created_by": "<string>",
"updated_by": "<string>"
}
],
"page": 123,
"size": 123,
"total": 123,
"pages": 123
}Lists the account’s beneficiaries, newest first by creation time. Disabled beneficiaries are included; deleted ones are not.
Each item is the full beneficiary object, including its non-deleted payout destinations.
Requires an API key with
read access on the payments scope.
Path Parameters
string
required
The account’s external ID (starts with
acct_)Query Parameters
array
Filter by status. Repeat the key to pass several values, for example
?statuses=active&statuses=disabled. Allowed values are active and disabled, lowercase; anything else returns 422.boolean
Whether to return only the account holder’s own beneficiaries.
false returns only third-party ones, and omitting it returns both.string
Only beneficiaries created on or after this ISO 8601 timestamp (inclusive)
string
Only beneficiaries created before this ISO 8601 timestamp (exclusive)
integer
default:"1"
Page number (minimum 1)
integer
default:"10"
Items per page (1-100)
Response
array
Beneficiary objects, newest first
Show Beneficiary fields
Show Beneficiary fields
string
Beneficiary identifier (starts with
bene_)string
Always returns
"beneficiary"string
Parent account external ID
string
Beneficiary type:
individual or businessstring
Title, or
nullstring
First name, or
nullstring
Middle name, or
nullstring
Last name, or
nullstring
Display name
string
Company name, or
nullstring
Email address, or
nullstring
Phone number, or
nullobject
Beneficiary address:
address_line, city, region (nullable), postal_code (nullable), countrystring
Payout country code
string
Beneficiary status:
active or disabledboolean
Whether Hop has verified the beneficiary’s details. Verification is a Hop operation with no client step, and it does not gate payouts today.
boolean
Whether the beneficiary is the account holder’s own bank account at another institution. Only a self-owned beneficiary can be paid from the trading account (a withdrawal); third-party beneficiaries are paid from a virtual account (a payout). See Create Payout.
array
The beneficiary’s non-deleted payout destinations
string
ISO 8601 timestamp when created
string
ISO 8601 timestamp when last updated
string
ID of the API key that created the beneficiary (starts with
ak_)string
Actor that last updated the beneficiary, or
nullinteger
Current page number
integer
Items per page
integer
Total number of items
integer
Total number of pages
Request Example
GET /v1/accounts/acct_ka44qsvpo8q3wtzuwfqf0h6u/beneficiaries?statuses=active&self_owned=false&size=10
Response Example
{
"items": [
{
"id": "bene_9gt1ummgx127biovlurm9mq2",
"object": "beneficiary",
"account_id": "acct_ka44qsvpo8q3wtzuwfqf0h6u",
"beneficiary_type": "individual",
"title": null,
"first_name": "John",
"middle_name": null,
"last_name": "Doe",
"display_name": "John Doe",
"company_name": null,
"email": "john.doe@example.com",
"phone": "+1234567890",
"address": {
"address_line": "123 Main St",
"city": "New York",
"region": "NY",
"postal_code": "10001",
"country": "US"
},
"country_code": "US",
"status": "active",
"verified": false,
"self_owned": false,
"payout_destinations": [
{
"id": "dest_7hq3nd0xk52vplf9rtb1wcue",
"object": "payout_destination",
"beneficiary_id": "bene_9gt1ummgx127biovlurm9mq2",
"country": "US",
"payment_rails": ["swift"],
"type": "bank_account",
"label": "Main Account",
"currency": "USD",
"network": null,
"status": "active",
"account_name": "John Doe",
"account_number_last4": "****7890",
"account_type": "checking",
"routing_number": "021000021",
"swift_code": null,
"iban_masked": null,
"clabe_last4": null,
"pix_key_last4": null,
"wallet_address_masked": null,
"bank_name": "Example Bank",
"bank_address": null,
"correspondent_bank_name": null,
"correspondent_bank_address": null,
"correspondent_bank_swift": null,
"account_holder": null,
"created": "2026-01-15T10:05:00Z",
"updated": "2026-01-15T10:05:00Z",
"created_by": "ak_0ub5w2xr8yl3qks6tcdn7m4v",
"updated_by": null
}
],
"created": "2026-01-15T10:00:00Z",
"updated": "2026-01-15T10:00:00Z",
"created_by": "ak_0ub5w2xr8yl3qks6tcdn7m4v",
"updated_by": null
}
],
"page": 1,
"size": 10,
"total": 1,
"pages": 1
}