Skip to main content
POST
Create Associated Person
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 first, or this endpoint returns 422 BUSINESS_RULE_VIOLATION. Once the group’s agreements are accepted, providers that support immediate validation check the edited details before Hop saves them. A refusal returns 422 with the rejected fields; a locked record returns 422 VIRTUAL_ACCOUNT_GROUP_ONBOARDING_LOCKED. If the provider cannot be reached or is still processing accepted agreements, the request returns 502; retry the request. These errors leave the edited details unchanged in Hop. An accepted change is saved even if it moves onboarding into review. Once the provider customer has been populated, this request submits only the new person’s details. Incomplete account details or another person’s incomplete details or standing rejection do not block this person’s submission. Initial customer creation still requires the complete account and associated-person details. Before agreements are accepted, while required details are incomplete, or for providers without immediate validation, eligible changes are saved and submitted in the background; any later rejection appears as a requirement on the group. 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 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

string
required
The account’s external ID (starts with acct_)

Request Body

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.
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.
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.
string
required
Max 100 characters, no digits.
string
required
Max 100 characters, no digits.
string
Max 100 characters.
string
required
Contact email for the person. Must be a valid address that no other associated person on the account uses.
string
E.164 format, for example +6581234567. Max 20 characters.
string
required
ISO 8601 date, for example 1985-06-21. Cannot be in the future.
string
required
ISO 3166-1 alpha-2 country of residence.
string
required
ISO 3166-1 alpha-2 nationality.
string
required
ISO 3166-1 alpha-2 country of birth.
string
Tax identification number, 1 to 255 characters. Must be sent together with tax_residence_country_code. Supplying one without the other is rejected.
string
ISO 3166-1 alpha-2 country of tax residence. Paired with tax_identification_number, as above.
string
Position held at the business, for example Director. Max 255 characters. Required for virtual account group onboarding when the person holds the account_representative role.
string
Ownership share as a percentage, above 0 and up to 100, at most 5 digits with 2 decimal places. Required when role or additional_roles includes ultimate_beneficial_owner, optional otherwise. 0, or a value outside 0 to 100, returns 422, and so does a share that takes the account’s associated persons above 100 in total. Virtual account group onboarding uses the share of an ultimate beneficial owner only.
string
direct or indirect: whether the share is held directly or through other entities. Only accepted together with ownership_percentage. When an ultimate beneficial owner has a percentage, the type is needed before verification can complete.
enum
The person’s estimated yearly income. Virtual account group onboarding requires it from an ultimate beneficial owner when the business’s registered or operating address is in California, Georgia, Hawaii, Louisiana, New Jersey, New York, Tennessee, Texas, Virginia, Washington, West Virginia or Wisconsin. One of:from_0_to_50k · from_50k_to_100k · from_100k_to_250k · from_250k_to_500k · from_500k_to_750k · from_750k_to_1m · above_1m
object
required
The person’s home address. Fields: address_line and city required, country required as an ISO 3166-1 alpha-2 code, postal_code optional to Hop but required by virtual account group onboarding. When country is US, region is required and must be a two-letter USPS state code such as CA (the 50 states, DC, AS, GU, MP, PR, VI); a full name such as California returns 422. Lowercase is accepted and stored uppercase. Outside the US, region is optional free text.
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 against the requirement that asks for them.
identifying_information is stored for submission to the provider and is not returned on any response.

Response

Returns 201 with the created person.
string
Associated person identifier (starts with aap_), and the value to pass as signer_id when responding to agreements.
string
Always returns "associated_person"
string
Parent account ID
string
ultimate_beneficial_owner, director, control_person or account_representative
string[]
Other roles the person holds. Empty when they hold only role
boolean
Whether the person may be named as signer_id on an agreement response
string
First name
string
Last name
string
Middle name, or null
string
Contact email, or null
string
Contact phone in E.164, or null
string
ISO 8601 date, or null
string
Country of residence, alpha-2
string
Nationality, alpha-2, or null
string
Country of birth, alpha-2, or null
string
Tax identification number, or null
string
Country of tax residence, alpha-2, or null
string
Position at the business, or null
string
Ownership share as a percentage, or null
string
direct or indirect, or null
string
Estimated yearly income band, for example from_100k_to_250k, or null
object
Residential address, or null
string
ISO 8601 timestamp when created
string
ISO 8601 timestamp when last updated
string
ID of the API key that created the person (starts with ak_)
string
Actor that last updated the person, or null

Errors

Request Example

Response Example