> ## 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 beneficiary under an account

Beneficiaries are recipient identities — either an individual or a business — owned by a platform end-customer account. Each beneficiary can hold one or more payment destinations (bank accounts), which are returned nested in the beneficiary object as `payment_destinations[]`. Payment destinations are separate resources: the Platform may add them when creating a beneficiary or later through the Payment Destinations endpoints, depending on its onboarding flow.

| Enum                | Values                   |
| ------------------- | ------------------------ |
| `BeneficiaryType`   | `individual`, `business` |
| `BeneficiaryStatus` | `active`, `disabled`     |

<Note>
  `beneficiary_type`, `first_name` / `middle_name` / `last_name`, `company_name`, `status`, and `verified` are immutable after creation — they cannot be changed via PATCH. Use the disable action to change status.
</Note>

Creates a beneficiary under an account. For `individual` beneficiaries, `first_name` and `last_name` are required; for `business` beneficiaries, `company_name` is required. The created beneficiary starts with an empty `payment_destinations` array — add destinations via the payment-destination endpoints.

## Path Parameters

<ParamField path="account_id" type="string" required>
  Id of the parent account (e.g. `acct_...`).
</ParamField>

## Request Body

<ParamField body="beneficiary_type" type="enum">
  `individual` | `business`. Defaults to `individual`. Immutable after creation.
</ParamField>

<ParamField body="title" type="string | null">
  Honorific or title. Max 20 characters.
</ParamField>

<ParamField body="first_name" type="string | null">
  Max 100 characters. **Conditional**: required when `beneficiary_type` is `individual`. Immutable after creation.
</ParamField>

<ParamField body="middle_name" type="string | null">
  Max 100 characters. Immutable after creation.
</ParamField>

<ParamField body="last_name" type="string | null">
  Max 100 characters. **Conditional**: required when `beneficiary_type` is `individual`. Immutable after creation.
</ParamField>

<ParamField body="display_name" type="string" required>
  Display name shown in listings and statements. Max 255 characters.
</ParamField>

<ParamField body="company_name" type="string | null">
  Max 255 characters. **Conditional**: required when `beneficiary_type` is `business`. Immutable after creation.
</ParamField>

<ParamField body="email" type="string | null">
  Max 255 characters; must contain `@`.
</ParamField>

<ParamField body="phone" type="string | null">
  Max 50 characters.
</ParamField>

<ParamField body="address" type="Address" required>
  Beneficiary address. All sub-fields are required.

  <Expandable title="child attributes">
    <ParamField body="address_line" type="string" required>
      Street address.
    </ParamField>

    <ParamField body="city" type="string" required>
      Max 100 characters.
    </ParamField>

    <ParamField body="region" type="string" required>
      State, province, or region. Max 100 characters.
    </ParamField>

    <ParamField body="postal_code" type="string" required>
      Max 20 characters.
    </ParamField>

    <ParamField body="country" type="string" required>
      Country code string. Send an ISO 3166-1 alpha-2 value; the shared Address schema does not enforce its length.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="country_code" type="PaymentCountry" required>
  ISO 3166-1 alpha-2 country code; must be on the supported payment-country allowlist.
</ParamField>

## Response

Returns 200 with the new resource's `id`. Use Get Beneficiary to retrieve the full object.

<ResponseField name="id" type="string">
  Id of the newly created beneficiary (e.g. `bene_...`).
</ResponseField>

<RequestExample>
  ```json Request theme={null}
  {
    "beneficiary_type": "business",
    "display_name": "Globex Ltd",
    "company_name": "Globex Limited",
    "email": "ap@globex.example",
    "address": {
      "address_line": "5 King St",
      "city": "London",
      "region": "London",
      "postal_code": "EC2V 8AS",
      "country": "GB"
    },
    "country_code": "GB"
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "id": "bene_9f2c1d7e8a4bx0y1z2a3b4c5"
  }
  ```
</ResponseExample>