Skip to main content
POST
/
v1
/
accounts
/
{account_id}
/
beneficiaries
Create Beneficiary
curl --request POST \
  --url https://api.hopnow.io/v1/accounts/{account_id}/beneficiaries \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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>"
  },
  "tax_id": "<string>",
  "country_code": "<string>",
  "note": "<string>"
}
'
{
  "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>"
  },
  "tax_id": "<string>",
  "country_code": "<string>",
  "note": "<string>",
  "status": "<string>",
  "verified": true,
  "payout_destinations": [
    {}
  ],
  "created": "<string>",
  "updated": "<string>"
}

​
Path Parameters

​
account_id
string
required
The account’s external ID (starts with acc_)

​
Request Body

​
beneficiary_type
string
default:"individual"
Type of beneficiary: individual or business
​
title
string
Title (e.g., Mr, Ms, Dr) - max 20 characters
​
first_name
string
required
First name (max 100 characters)
​
middle_name
string
Middle name (max 100 characters)
​
last_name
string
required
Last name (max 100 characters)
​
display_name
string
required
Display name for the beneficiary (max 255 characters)
​
company_name
string
Company name (required for business beneficiaries, max 255 characters)
​
email
string
required
Email address (max 255 characters)
​
phone
string
required
Phone number with country code (max 50 characters)
​
address
object
required
Beneficiary address
​
tax_id
string
Tax identification number (max 50 characters)
​
country_code
string
required
Payout country code (ISO 3166-1 alpha-2)
​
note
string
Internal notes or comments

​
Response

​
id
string
Beneficiary identifier (starts with bene_)
​
object
string
Always returns "beneficiary"
​
account_id
string
Parent account external ID
​
beneficiary_type
string
Beneficiary type: individual or business
​
title
string
Title (e.g., Mr, Ms, Dr)
​
first_name
string
First name
​
middle_name
string
Middle name
​
last_name
string
Last name
​
display_name
string
Display name
​
company_name
string
Company name
​
email
string
Email address
​
phone
string
Phone number
​
address
object
Beneficiary address
​
tax_id
string
Tax identification number
​
country_code
string
Payout country code
​
note
string
Internal notes or comments
​
status
string
Beneficiary status: active, disabled, or inactive
​
verified
boolean
Whether beneficiary has been verified
​
payout_destinations
array
Array of payout destination objects
​
created
string
ISO 8601 timestamp when created
​
updated
string
ISO 8601 timestamp when last updated

​
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,
  "payout_destinations": [],
  "created": "2024-01-15T10:00:00Z",
  "updated": "2024-01-15T10:00:00Z"
}