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

> Attach a UBO, director, control person, partner, or authorized signer to a business account

Associated persons are the UBOs, directors, control persons, partners where applicable, and authorized signers attached to a business account as part of KYB. They can be supplied inline when creating the account, or managed afterwards through the endpoints below. Authorized signatory status is represented by `is_signer=true`. Creates and updates recompute the account's onboarding requirements and are blocked once the account's `kyc_status` is terminal (`approved` / `rejected`).

| Enum                  | Values                                                    |
| --------------------- | --------------------------------------------------------- |
| `role`                | `ultimate_beneficial_owner`, `director`, `control_person` |
| `verification_status` | `under_review`, `approved`, `rejected`                    |

This endpoint attaches a UBO, director, control person, partner, or authorized signer to the account and recomputes onboarding requirements.

<Note>
  Unlike account creation, this endpoint does not take an `Idempotency-Key` header.
</Note>

## Path Parameters

<ParamField path="customer_id" type="string" required>
  Id of the Platform customer (e.g. `cus_…`).
</ParamField>

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

## Request Body

<ParamField body="role" type="enum" required>
  One of `ultimate_beneficial_owner`, `director`, `control_person`.
</ParamField>

<ParamField body="is_signer" type="boolean">
  Whether this person is an authorized signer for the entity and eligible to sign agreements via Submit Agreement Actions. Defaults to `false`.
</ParamField>

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

<ParamField body="middle_name" type="string | null">
  Middle name, if any. Max 100 characters.
</ParamField>

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

<ParamField body="email" type="email" required>
  Contact email address of the person.
</ParamField>

<ParamField body="phone_number" type="string | null">
  Contact phone number.
</ParamField>

<ParamField body="date_of_birth" type="date" required>
  Date of birth, ISO 8601 (`YYYY-MM-DD`).
</ParamField>

<ParamField body="country_code" type="string" required>
  Country of residence, ISO 3166-1 alpha-2 (2 letters, e.g. `DE`).
</ParamField>

<ParamField body="nationality" type="string" required>
  Nationality, ISO 3166-1 alpha-2 (2 letters).
</ParamField>

<ParamField body="ownership_percentage" type="decimal | null">
  **Conditional.** Ownership stake with at most 5 digits and 2 decimal places. The API does not enforce a 0–100 range. Required when creating a person whose `role` is `ultimate_beneficial_owner`; optional otherwise.
</ParamField>

<ParamField body="residential_address" type="Address" required>
  Residential address of the person.

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

    <ParamField body="city" type="string" required>
      City. 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>
      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="identifying_information" type="array">
  Identity document data for the person (type, number, issuing country). Document images are submitted by the person inside their Verification Session, not through this API. Defaults to `[]`.

  <Expandable title="child attributes">
    <ParamField body="type" type="string" required>
      Document type string, maximum 100 characters (for example `passport`, `drivers_license`, or `national_id`). The API does not restrict this field to a fixed enum.
    </ParamField>

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

    <ParamField body="issuing_country" type="string | null">
      Issuing country, ISO 3166-1 alpha-2 (2 letters).
    </ParamField>
  </Expandable>
</ParamField>

## Response

Returns `200` with the new resource's `id`. Use [Get Associated Person](/va/associated-persons/get-associated-person) to retrieve the full object.

<ResponseField name="id" type="string">
  Id of the newly created associated person (e.g. `aap_…`).
</ResponseField>

<RequestExample>
  ```json Request theme={null}
  {
    "role": "ultimate_beneficial_owner",
    "is_signer": true,
    "first_name": "Jane",
    "last_name": "Roe",
    "email": "jane@acme.example",
    "phone_number": "+6581234567",
    "date_of_birth": "1985-02-20",
    "country_code": "DE",
    "nationality": "DE",
    "ownership_percentage": "55.00",
    "residential_address": {
      "address_line": "2 Park Ave",
      "city": "Berlin",
      "region": "BE",
      "postal_code": "10117",
      "country": "DE"
    },
    "identifying_information": [
      { "type": "passport", "number": "C01X00T47", "issuing_country": "DE" }
    ]
  }
  ```
</RequestExample>

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