> ## 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.

# Update Associated Person

> Correct or complete the details of a beneficial owner, director or control person

Updates one associated person. Send only the fields that change; anything you omit keeps its stored value.

Requires an API key with `write` access on the `accounts` scope. Like creation, this endpoint works only on **business** accounts.

The patch is merged onto the stored record and the merged result is revalidated in full, so a change can be rejected because of a field you did not send: changing `role` to `ultimate_beneficial_owner` without an `ownership_percentage` already on record fails.

Saving a change re-triggers virtual account group onboarding, so a requirement that was waiting on this person's details clears on its own. A patch that changes nothing is a no-op and returns the record unchanged.

## Path Parameters

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

<ParamField path="person_id" type="string" required>
  The associated person's external ID (starts with `aap_`). One belonging to another account returns `404`.
</ParamField>

## Request Body

Every field is optional and carries the same type, format and constraint as on [Create Associated Person](/fx/api-reference/associated-persons/create-associated-person): `role`, `additional_roles`, `is_signer`, `first_name`, `last_name`, `middle_name`, `email`, `phone_number`, `date_of_birth`, `country_code`, `nationality`, `birth_country_code`, `tax_identification_number`, `tax_residence_country_code`, `position`, `ownership_percentage`, `ownership_type`, `residential_address`, `identifying_information`.

<ParamField body="role" type="string">
  May be changed between `ultimate_beneficial_owner`, `director`, `control_person` and `account_representative`. `account_holder` is reserved and rejected. A person whose `role` is `account_holder` cannot be updated through this endpoint.
</ParamField>

<ParamField body="additional_roles" type="string[]">
  Replaced wholesale. Send the full list of other roles, or `[]` to remove them all; `null` is rejected.
</ParamField>

<ParamField body="residential_address" type="object">
  Replaced wholesale, not merged field by field. Send the complete address.
</ParamField>

<ParamField body="identifying_information" type="object[]">
  Replaced wholesale. Send the full list you want stored, not just the new entry.
</ParamField>

Omitting a field leaves it untouched. Sending it explicitly as `null` **clears** it, which works for the optional fields: `middle_name`, `phone_number`, `position`, `ownership_type`, `ownership_percentage` (clear `ownership_type` with it), and the tax pair. Sending `null` for a field that is required on create fails with `422`.

## Response

Returns `200` with the updated person, in the same shape as [Create Associated Person](/fx/api-reference/associated-persons/create-associated-person).

## Errors

| Status | `code` | When |
| - | - | - |
| `422` | `VALIDATION_ERROR` | The body carries a field this endpoint does not accept; `validation_errors` names it |
| `422` | `BUSINESS_RULE_VIOLATION` | The account is not a business account, or the person holds the reserved `account_holder` role |
| `422` | `BUSINESS_RULE_VIOLATION` | `role` or `additional_roles` is set to include `account_holder` |
| `422` | `VALIDATION_ERROR` | The merged record fails validation: `details.errors` lists each offending field. Common causes: `role` changed to `ultimate_beneficial_owner` with no `ownership_percentage` on record, `role` changed to a value already in `additional_roles`, an `ownership_type` left without its percentage, or a tax number left without its residence country |
| `404` | `RESOURCE_NOT_FOUND` | `account_id` or `person_id` is unknown, or the person belongs to a different account |

## Request Example

```json theme={null}
{
  "email": "maya.chen@acme.example",
  "ownership_percentage": "55.00",
  "ownership_type": "direct",
  "is_signer": true
}
```

## 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.chen@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": "55.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-16T05:02:44Z",
  "created_by": "ak_9a3yfd2ro3jeoqqalbx8jew1",
  "updated_by": "ak_9a3yfd2ro3jeoqqalbx8jew1"
}
```