> ## 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 Associated Person

> Add a beneficial owner, director or control person to a business account

An associated person is a natural person behind a business entity: an ultimate beneficial owner, a director, or someone who exercises control. Virtual account onboarding needs them for two reasons: the provider verifies each person, and one of them signs the provider agreements.

Associated persons exist only on business accounts: set the account's identity to `type: "business"` through [Update Account](/fx/api-reference/accounts/update-account-identity) first, or this endpoint returns `422` `BUSINESS_RULE_VIOLATION`.

Requires an API key with `write` access on the `accounts` scope.

## Who signs the agreements

Set `is_signer: true` on at least one person. A business virtual account group cannot complete its agreements without one: [Submit Agreement Actions](/fx/api-reference/virtual-account-groups/submit-agreement-actions) requires a `signer_id`, and the person it names must carry this flag. Setting it on more than one person is allowed. You choose which one signs at the time.

## Path Parameters

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

## Request Body

<ParamField body="role" type="string" required>
  The person's role on the entity: `ultimate_beneficial_owner`, `director`, `control_person` or `account_representative`. `account_holder` is reserved for Hop's own use and is rejected here.

  Hop submits exactly the roles you declare. It does not add one for you: a large owner is not treated as a control person, and a signer is not treated as an account representative.
</ParamField>

<ParamField body="additional_roles" type="string[]" default="[]">
  Other roles the same person holds, from the same values as `role`, for example an owner who is also the control person. Must not repeat `role` or list a value twice.
</ParamField>

<ParamField body="is_signer" type="boolean" default="false">
  Whether this person may sign agreements on behalf of the entity. It gives signing authority only; declare an account representative with the `account_representative` role.
</ParamField>

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

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

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

<ParamField body="email" type="string" required>
  Contact email for the person. Must be a valid address.
</ParamField>

<ParamField body="phone_number" type="string">
  E.164 format, for example `+6581234567`. Max 20 characters.
</ParamField>

<ParamField body="date_of_birth" type="string" required>
  ISO 8601 date, for example `1985-06-21`.
</ParamField>

<ParamField body="country_code" type="string" required>
  ISO 3166-1 alpha-2 country of residence.
</ParamField>

<ParamField body="nationality" type="string" required>
  ISO 3166-1 alpha-2 nationality.
</ParamField>

<ParamField body="birth_country_code" type="string" required>
  ISO 3166-1 alpha-2 country of birth.
</ParamField>

<ParamField body="tax_identification_number" type="string">
  Tax identification number, 1 to 255 characters. Must be sent together with `tax_residence_country_code`. Supplying one without the other is rejected.
</ParamField>

<ParamField body="tax_residence_country_code" type="string">
  ISO 3166-1 alpha-2 country of tax residence. Paired with `tax_identification_number`, as above.
</ParamField>

<ParamField body="position" type="string">
  Position held at the business, for example `Director`. Max 255 characters.
</ParamField>

<ParamField body="ownership_percentage" type="string">
  Ownership share as a percentage, from 0 to 100, at most 5 digits with 2 decimal places. **Required when `role` or `additional_roles` includes `ultimate_beneficial_owner`**, optional otherwise. A value outside 0 to 100 returns `422`.
</ParamField>

<ParamField body="ownership_type" type="string">
  `direct` or `indirect`: whether the share is held directly or through other entities. Only accepted together with `ownership_percentage`. When a percentage is set, the type is needed before verification can complete.
</ParamField>

<ParamField body="residential_address" type="object" required>
  The person's home address. Fields: `address_line` and `city` required, `country` required as an ISO 3166-1 alpha-2 code, `region` and `postal_code` optional. The provider may later require `postal_code`, so supply it when the country has one.
</ParamField>

<ParamField body="identifying_information" type="object[]" default="[]">
  Identity document reference numbers. Each entry carries `type` (for example `passport`, `national_id`, `drivers_license`, max 100 characters), `number` (max 100 characters) and an optional `issuing_country` as an alpha-2 code.

  Reference numbers only: document files go through [Upload Document](/fx/api-reference/virtual-account-groups/upload-document) against the requirement that asks for them.
</ParamField>

`identifying_information` is stored for submission to the provider and is not returned on any response.

## Response

Returns `201` with the created person.

<ResponseField name="id" type="string">
  Associated person identifier (starts with `aap_`), and the value to pass as `signer_id` when responding to agreements.
</ResponseField>

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

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

<ResponseField name="role" type="string">
  `ultimate_beneficial_owner`, `director`, `control_person` or `account_representative`
</ResponseField>

<ResponseField name="additional_roles" type="string[]">
  Other roles the person holds. Empty when they hold only `role`
</ResponseField>

<ResponseField name="is_signer" type="boolean">
  Whether the person may be named as `signer_id` on an agreement response
</ResponseField>

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

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

<ResponseField name="middle_name" type="string">
  Middle name, or `null`
</ResponseField>

<ResponseField name="email" type="string">
  Contact email, or `null`
</ResponseField>

<ResponseField name="phone_number" type="string">
  Contact phone in E.164, or `null`
</ResponseField>

<ResponseField name="date_of_birth" type="string">
  ISO 8601 date, or `null`
</ResponseField>

<ResponseField name="country_code" type="string">
  Country of residence, alpha-2
</ResponseField>

<ResponseField name="nationality" type="string">
  Nationality, alpha-2, or `null`
</ResponseField>

<ResponseField name="birth_country_code" type="string">
  Country of birth, alpha-2, or `null`
</ResponseField>

<ResponseField name="tax_identification_number" type="string">
  Tax identification number, or `null`
</ResponseField>

<ResponseField name="tax_residence_country_code" type="string">
  Country of tax residence, alpha-2, or `null`
</ResponseField>

<ResponseField name="position" type="string">
  Position at the business, or `null`
</ResponseField>

<ResponseField name="ownership_percentage" type="string">
  Ownership share as a percentage, or `null`
</ResponseField>

<ResponseField name="ownership_type" type="string">
  `direct` or `indirect`, or `null`
</ResponseField>

<ResponseField name="residential_address" type="object">
  Residential address, or `null`
</ResponseField>

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

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

<ResponseField name="created_by" type="string">
  ID of the API key that created the person (starts with `ak_`)
</ResponseField>

<ResponseField name="updated_by" type="string">
  Actor that last updated the person, or `null`
</ResponseField>

## Errors

| Status | `code` | When |
| - | - | - |
| `422` | `BUSINESS_RULE_VIOLATION` | The account is not a business account. `details.account_identity_type` carries what it is, or `null` when no identity has been set yet |
| `422` | `BUSINESS_RULE_VIOLATION` | `role` or `additional_roles` includes `account_holder`, which is reserved |
| `422` | `VALIDATION_ERROR` | A field is missing or malformed: `ownership_percentage` absent for an ultimate beneficial owner, `ownership_type` without `ownership_percentage`, `additional_roles` repeating a role, `tax_identification_number` without `tax_residence_country_code`, a country code that is not alpha-2, a phone that is not E.164, or an invalid email |
| `403` | `ACCESS_DENIED` | The account exists but belongs to another organization |
| `404` | `RESOURCE_NOT_FOUND` | `account_id` is unknown or deleted |

## Request Example

```json theme={null}
{
  "role": "ultimate_beneficial_owner",
  "additional_roles": ["control_person"],
  "is_signer": true,
  "first_name": "Maya",
  "last_name": "Chen",
  "email": "maya@acme.example",
  "phone_number": "+6581234567",
  "date_of_birth": "1985-06-21",
  "country_code": "SG",
  "nationality": "SG",
  "birth_country_code": "SG",
  "tax_identification_number": "S1234567D",
  "tax_residence_country_code": "SG",
  "position": "Director",
  "ownership_percentage": "60.00",
  "ownership_type": "direct",
  "residential_address": {
    "address_line": "10 Marina Boulevard, #23-01",
    "city": "Singapore",
    "region": "Central Region",
    "postal_code": "018983",
    "country": "SG"
  },
  "identifying_information": [
    {"type": "passport", "number": "E1234567A", "issuing_country": "SG"}
  ]
}
```

## Response Example

```json theme={null}
{
  "id": "aap_3f8k1m5p9r2t6v4x7z0b3n5q",
  "object": "associated_person",
  "account_id": "acct_9f2a7c1e6a2b4f3c9b8d2e5a",
  "role": "ultimate_beneficial_owner",
  "additional_roles": ["control_person"],
  "is_signer": true,
  "first_name": "Maya",
  "last_name": "Chen",
  "middle_name": null,
  "email": "maya@acme.example",
  "phone_number": "+6581234567",
  "date_of_birth": "1985-06-21",
  "country_code": "SG",
  "nationality": "SG",
  "birth_country_code": "SG",
  "tax_identification_number": "S1234567D",
  "tax_residence_country_code": "SG",
  "position": "Director",
  "ownership_percentage": "60.00",
  "ownership_type": "direct",
  "residential_address": {
    "address_line": "10 Marina Boulevard, #23-01",
    "city": "Singapore",
    "region": "Central Region",
    "postal_code": "018983",
    "country": "SG"
  },
  "created": "2026-09-16T03:14:01Z",
  "updated": "2026-09-16T03:14:01Z",
  "created_by": "ak_9a3yfd2ro3jeoqqalbx8jew1",
  "updated_by": null
}
```