Create Beneficiary

curl --request POST \
  --url https://api.hopnow.io/v1/accounts/{account_id}/beneficiaries \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "beneficiary_type": "<string>",
  "display_name": "<string>",
  "first_name": "<string>",
  "last_name": "<string>",
  "company_name": "<string>",
  "title": "<string>",
  "middle_name": "<string>",
  "email": "<string>",
  "phone": "<string>",
  "address": {
    "address_line": "<string>",
    "city": "<string>",
    "region": "<string>",
    "postal_code": "<string>",
    "country": "<string>"
  },
  "country_code": "<string>",
  "self_owned": true
}
'

import requests

url = "https://api.hopnow.io/v1/accounts/{account_id}/beneficiaries"

payload = {
    "beneficiary_type": "<string>",
    "display_name": "<string>",
    "first_name": "<string>",
    "last_name": "<string>",
    "company_name": "<string>",
    "title": "<string>",
    "middle_name": "<string>",
    "email": "<string>",
    "phone": "<string>",
    "address": {
        "address_line": "<string>",
        "city": "<string>",
        "region": "<string>",
        "postal_code": "<string>",
        "country": "<string>"
    },
    "country_code": "<string>",
    "self_owned": True
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    beneficiary_type: '<string>',
    display_name: '<string>',
    first_name: '<string>',
    last_name: '<string>',
    company_name: '<string>',
    title: '<string>',
    middle_name: '<string>',
    email: '<string>',
    phone: '<string>',
    address: {
      address_line: '<string>',
      city: '<string>',
      region: '<string>',
      postal_code: '<string>',
      country: '<string>'
    },
    country_code: '<string>',
    self_owned: true
  })
};

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 => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'beneficiary_type' => '<string>',
    'display_name' => '<string>',
    'first_name' => '<string>',
    'last_name' => '<string>',
    'company_name' => '<string>',
    'title' => '<string>',
    'middle_name' => '<string>',
    'email' => '<string>',
    'phone' => '<string>',
    'address' => [
        'address_line' => '<string>',
        'city' => '<string>',
        'region' => '<string>',
        'postal_code' => '<string>',
        'country' => '<string>'
    ],
    'country_code' => '<string>',
    'self_owned' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "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"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.hopnow.io/v1/accounts/{account_id}/beneficiaries"

	payload := strings.NewReader("{\n  \"beneficiary_type\": \"<string>\",\n  \"display_name\": \"<string>\",\n  \"first_name\": \"<string>\",\n  \"last_name\": \"<string>\",\n  \"company_name\": \"<string>\",\n  \"title\": \"<string>\",\n  \"middle_name\": \"<string>\",\n  \"email\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"address\": {\n    \"address_line\": \"<string>\",\n    \"city\": \"<string>\",\n    \"region\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"country\": \"<string>\"\n  },\n  \"country_code\": \"<string>\",\n  \"self_owned\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.hopnow.io/v1/accounts/{account_id}/beneficiaries")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"beneficiary_type\": \"<string>\",\n  \"display_name\": \"<string>\",\n  \"first_name\": \"<string>\",\n  \"last_name\": \"<string>\",\n  \"company_name\": \"<string>\",\n  \"title\": \"<string>\",\n  \"middle_name\": \"<string>\",\n  \"email\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"address\": {\n    \"address_line\": \"<string>\",\n    \"city\": \"<string>\",\n    \"region\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"country\": \"<string>\"\n  },\n  \"country_code\": \"<string>\",\n  \"self_owned\": true\n}")
  .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::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"beneficiary_type\": \"<string>\",\n  \"display_name\": \"<string>\",\n  \"first_name\": \"<string>\",\n  \"last_name\": \"<string>\",\n  \"company_name\": \"<string>\",\n  \"title\": \"<string>\",\n  \"middle_name\": \"<string>\",\n  \"email\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"address\": {\n    \"address_line\": \"<string>\",\n    \"city\": \"<string>\",\n    \"region\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"country\": \"<string>\"\n  },\n  \"country_code\": \"<string>\",\n  \"self_owned\": true\n}"

response = http.request(request)
puts response.read_body

{
  "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": {
    "address_line": "<string>",
    "city": "<string>",
    "region": "<string>",
    "postal_code": "<string>",
    "country": "<string>"
  },
  "country_code": "<string>",
  "status": "<string>",
  "verified": true,
  "self_owned": true,
  "payout_destinations": [
    {}
  ],
  "created": "<string>",
  "updated": "<string>",
  "created_by": "<string>",
  "updated_by": "<string>"
}

POST

accounts

{account_id}

beneficiaries

Create Beneficiary

curl --request POST \
  --url https://api.hopnow.io/v1/accounts/{account_id}/beneficiaries \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "beneficiary_type": "<string>",
  "display_name": "<string>",
  "first_name": "<string>",
  "last_name": "<string>",
  "company_name": "<string>",
  "title": "<string>",
  "middle_name": "<string>",
  "email": "<string>",
  "phone": "<string>",
  "address": {
    "address_line": "<string>",
    "city": "<string>",
    "region": "<string>",
    "postal_code": "<string>",
    "country": "<string>"
  },
  "country_code": "<string>",
  "self_owned": true
}
'

import requests

url = "https://api.hopnow.io/v1/accounts/{account_id}/beneficiaries"

payload = {
    "beneficiary_type": "<string>",
    "display_name": "<string>",
    "first_name": "<string>",
    "last_name": "<string>",
    "company_name": "<string>",
    "title": "<string>",
    "middle_name": "<string>",
    "email": "<string>",
    "phone": "<string>",
    "address": {
        "address_line": "<string>",
        "city": "<string>",
        "region": "<string>",
        "postal_code": "<string>",
        "country": "<string>"
    },
    "country_code": "<string>",
    "self_owned": True
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    beneficiary_type: '<string>',
    display_name: '<string>',
    first_name: '<string>',
    last_name: '<string>',
    company_name: '<string>',
    title: '<string>',
    middle_name: '<string>',
    email: '<string>',
    phone: '<string>',
    address: {
      address_line: '<string>',
      city: '<string>',
      region: '<string>',
      postal_code: '<string>',
      country: '<string>'
    },
    country_code: '<string>',
    self_owned: true
  })
};

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 => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'beneficiary_type' => '<string>',
    'display_name' => '<string>',
    'first_name' => '<string>',
    'last_name' => '<string>',
    'company_name' => '<string>',
    'title' => '<string>',
    'middle_name' => '<string>',
    'email' => '<string>',
    'phone' => '<string>',
    'address' => [
        'address_line' => '<string>',
        'city' => '<string>',
        'region' => '<string>',
        'postal_code' => '<string>',
        'country' => '<string>'
    ],
    'country_code' => '<string>',
    'self_owned' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "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"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.hopnow.io/v1/accounts/{account_id}/beneficiaries"

	payload := strings.NewReader("{\n  \"beneficiary_type\": \"<string>\",\n  \"display_name\": \"<string>\",\n  \"first_name\": \"<string>\",\n  \"last_name\": \"<string>\",\n  \"company_name\": \"<string>\",\n  \"title\": \"<string>\",\n  \"middle_name\": \"<string>\",\n  \"email\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"address\": {\n    \"address_line\": \"<string>\",\n    \"city\": \"<string>\",\n    \"region\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"country\": \"<string>\"\n  },\n  \"country_code\": \"<string>\",\n  \"self_owned\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.hopnow.io/v1/accounts/{account_id}/beneficiaries")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"beneficiary_type\": \"<string>\",\n  \"display_name\": \"<string>\",\n  \"first_name\": \"<string>\",\n  \"last_name\": \"<string>\",\n  \"company_name\": \"<string>\",\n  \"title\": \"<string>\",\n  \"middle_name\": \"<string>\",\n  \"email\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"address\": {\n    \"address_line\": \"<string>\",\n    \"city\": \"<string>\",\n    \"region\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"country\": \"<string>\"\n  },\n  \"country_code\": \"<string>\",\n  \"self_owned\": true\n}")
  .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::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"beneficiary_type\": \"<string>\",\n  \"display_name\": \"<string>\",\n  \"first_name\": \"<string>\",\n  \"last_name\": \"<string>\",\n  \"company_name\": \"<string>\",\n  \"title\": \"<string>\",\n  \"middle_name\": \"<string>\",\n  \"email\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"address\": {\n    \"address_line\": \"<string>\",\n    \"city\": \"<string>\",\n    \"region\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"country\": \"<string>\"\n  },\n  \"country_code\": \"<string>\",\n  \"self_owned\": true\n}"

response = http.request(request)
puts response.read_body

{
  "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": {
    "address_line": "<string>",
    "city": "<string>",
    "region": "<string>",
    "postal_code": "<string>",
    "country": "<string>"
  },
  "country_code": "<string>",
  "status": "<string>",
  "verified": true,
  "self_owned": true,
  "payout_destinations": [
    {}
  ],
  "created": "<string>",
  "updated": "<string>",
  "created_by": "<string>",
  "updated_by": "<string>"
}

A beneficiary is the person or company that receives a payout. Creating one records identity and address only. Add a payout destination to it before you can send money. New beneficiaries are always created with status: "active" and verified: false; there is no client-facing verification step. Requires an API key with write access on the payments scope.

Path Parameters

string

required

The account’s external ID (starts with acct_)

Request Body

string

default:"individual"

Type of beneficiary: individual or business. Decides which name fields are required.

string

required

Name shown for the beneficiary across the API and the portal (max 255 characters)

string

First name (max 100 characters). Required when beneficiary_type is individual.

string

Last name (max 100 characters). Required when beneficiary_type is individual.

string

Company name (max 255 characters). Required when beneficiary_type is business.

string

Title, for example Mr, Ms, Dr (max 20 characters)

string

Middle name (max 100 characters)

string

Email address (max 255 characters). Must contain @ when present.

string

Phone number with country code (max 50 characters)

object

required

Beneficiary address

Show Address fields

string

required

Complete street address

string

required

City name (max 100 characters)

string

State, province, or region (max 100 characters)

string

Postal code (max 20 characters)

string

required

ISO 3166-1 alpha-2 country code

string

required

The country the payout is delivered to, as an ISO 3166-1 alpha-2 code (it can differ from address.country, which is where the beneficiary lives and is unrestricted). A country Hop does not deliver to is rejected with 422. See Rejected countries.

boolean

required

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.

Response

string

Beneficiary identifier (starts with bene_)

string

Always returns "beneficiary"

string

Parent account external ID

string

Beneficiary type: individual or business

string

Title, or null

string

First name, or null

string

Middle name, or null

string

Last name, or null

string

Display name

string

Company name, or null

string

Email address, or null

string

Phone number, or null

object

Beneficiary address

Show Address fields

string

Complete street address

string

City

string

State, province, or region, or null

string

Postal code, or null

string

ISO 3166-1 alpha-2 country code

string

Payout country code

string

Beneficiary status: active or disabled. A new beneficiary is always active.

boolean

Whether Hop has verified the beneficiary’s details. Verification is a Hop operation with no client step, and it does not gate payouts today. Always false on create.

boolean

array

Payout destinations attached to this beneficiary. Always [] here. The list is populated once destinations are added.

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 null

Errors

Status	`code`	When
`422`	`MISSING_REQUIRED_FIELD`	A conditionally required field is absent; `details.field` names it: `first_name, last_name` for an individual, `company_name` for a business, or `address.address_line`, `address.city`, `address.country`
`422`	`INVALID_FIELD_FORMAT`	`email` was supplied without an `@`; `details.field` is `email`
`422`	`VALIDATION_ERROR`	The body failed schema validation, for example an unsupported `country_code` or a value over its maximum length; `validation_errors` lists each field

Request Example

{
  "beneficiary_type": "individual",
  "first_name": "John",
  "last_name": "Doe",
  "display_name": "John Doe",
  "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",
  "self_owned": false
}

Response Example

{
  "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": [],
  "created": "2026-01-15T10:00:00Z",
  "updated": "2026-01-15T10:00:00Z",
  "created_by": "ak_0ub5w2xr8yl3qks6tcdn7m4v",
  "updated_by": null
}

Getting started

API basics

Endpoints

Webhooks

Create Beneficiary

Path Parameters

Request Body

Response

Errors

Request Example

Response Example

​Path Parameters

​Request Body

​Response

​Errors

​Request Example

​Response Example

Path Parameters

Request Body

Response

Errors

Request Example

Response Example