> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.hopnow.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Beneficiary

> Create a new beneficiary for receiving payouts

## Path Parameters

<ParamField path="account_id" type="string" required>
  The account's external ID (starts with `acc_`)
</ParamField>

## Request Body

<ParamField body="beneficiary_type" type="string" default="individual">
  Type of beneficiary: `individual` or `business`
</ParamField>

<ParamField body="title" type="string">
  Title (e.g., Mr, Ms, Dr) - max 20 characters
</ParamField>

<ParamField body="first_name" type="string" required>
  First name (max 100 characters)
</ParamField>

<ParamField body="middle_name" type="string">
  Middle name (max 100 characters)
</ParamField>

<ParamField body="last_name" type="string" required>
  Last name (max 100 characters)
</ParamField>

<ParamField body="display_name" type="string" required>
  Display name for the beneficiary (max 255 characters)
</ParamField>

<ParamField body="company_name" type="string">
  Company name (required for business beneficiaries, max 255 characters)
</ParamField>

<ParamField body="email" type="string" required>
  Email address (max 255 characters)
</ParamField>

<ParamField body="phone" type="string" required>
  Phone number with country code (max 50 characters)
</ParamField>

<ParamField body="address" type="object" required>
  Beneficiary address

  <Expandable title="Address fields">
    <ParamField body="address_line" type="string" required>
      Complete street address
    </ParamField>

    <ParamField body="city" type="string" required>
      City name (max 100 characters)
    </ParamField>

    <ParamField body="region" type="string" required>
      State/Province/Region (max 100 characters)
    </ParamField>

    <ParamField body="postal_code" type="string" required>
      Postal code (max 20 characters)
    </ParamField>

    <ParamField body="country" type="string" required>
      ISO 3166-1 alpha-2 country code
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="tax_id" type="string">
  Tax identification number (max 50 characters)
</ParamField>

<ParamField body="country_code" type="string" required>
  Payout country code (ISO 3166-1 alpha-2)
</ParamField>

<ParamField body="note" type="string">
  Internal notes or comments
</ParamField>

## Response

<ResponseField name="id" type="string">
  Beneficiary identifier (starts with `bene_`)
</ResponseField>

<ResponseField name="object" type="string">
  Always returns `"beneficiary"`
</ResponseField>

<ResponseField name="account_id" type="string">
  Parent account external ID
</ResponseField>

<ResponseField name="beneficiary_type" type="string">
  Beneficiary type: `individual` or `business`
</ResponseField>

<ResponseField name="title" type="string">
  Title (e.g., Mr, Ms, Dr)
</ResponseField>

<ResponseField name="first_name" type="string">
  First name
</ResponseField>

<ResponseField name="middle_name" type="string">
  Middle name
</ResponseField>

<ResponseField name="last_name" type="string">
  Last name
</ResponseField>

<ResponseField name="display_name" type="string">
  Display name
</ResponseField>

<ResponseField name="company_name" type="string">
  Company name
</ResponseField>

<ResponseField name="email" type="string">
  Email address
</ResponseField>

<ResponseField name="phone" type="string">
  Phone number
</ResponseField>

<ResponseField name="address" type="object">
  Beneficiary address

  <Expandable title="Address Fields">
    <ResponseField name="address_line" type="string">
      Street address
    </ResponseField>

    <ResponseField name="city" type="string">
      City name
    </ResponseField>

    <ResponseField name="region" type="string">
      State/Province/Region
    </ResponseField>

    <ResponseField name="postal_code" type="string">
      Postal code
    </ResponseField>

    <ResponseField name="country" type="string">
      ISO 3166-1 alpha-2 country code
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="tax_id" type="string">
  Tax identification number
</ResponseField>

<ResponseField name="country_code" type="string">
  Payout country code
</ResponseField>

<ResponseField name="note" type="string">
  Internal notes or comments
</ResponseField>

<ResponseField name="status" type="string">
  Beneficiary status: `active`, `disabled`, or `inactive`
</ResponseField>

<ResponseField name="verified" type="boolean">
  Whether beneficiary has been verified
</ResponseField>

<ResponseField name="payout_destinations" type="array">
  Array of payout destination objects
</ResponseField>

<ResponseField name="created" type="string">
  ISO 8601 timestamp when created
</ResponseField>

<ResponseField name="updated" type="string">
  ISO 8601 timestamp when last updated
</ResponseField>

## Response Example

```json theme={null}
{
  "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"
}
```