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

> Set or correct the legal identity Hop submits when onboarding an account to a virtual account provider

An account's identity profile is the legal entity behind it: a company with its registration number and registered address, or a natural person with their date of birth and nationality. Virtual account onboarding submits it to the provider, so a group cannot progress until the profile is complete.

The profile is separate from your organization's KYB record. Providers require fields Hop does not hold, such as incorporation date or tax residence, so you supply the full profile here.

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

Validation runs on the stored profile after your changes are merged in. The first call on an account with no profile must include every required field; later calls can send only the fields that change. A partial first call returns `422` listing what is missing.

Saving a profile re-triggers virtual account group onboarding. If a group is already open and showing the `account_profile.required` requirement, that requirement clears on its own. You do not create the group again.

## Path Parameters

<ParamField path="customer_id" type="string" required>
  The customer's external ID (starts with `cus_`)
</ParamField>

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

The identity profile is the only writable part of an account. `name`, `status`, `type` and every other field on the account are set by Hop, and are not accepted here: the body is rejected with `422 VALIDATION_ERROR` naming the unknown key, not silently ignored.

## Request Body

<ParamField body="type" type="string" required>
  Entity type: `business` or `individual`. It selects which field group below applies.

  `type` is a discriminator and cannot be changed once a profile exists: a patch whose `type` differs from the stored one is rejected with `422`. Send the stored value on every call.
</ParamField>

### Business fields: `type: "business"`

Required on the first call: `business_legal_name`, `business_type`, `registered_address`, `business_registration_number` and `incorporation_date`. Everything else is optional to Hop, but a provider will ask for most of it before it approves onboarding, and the outstanding items appear as requirements on [Get Virtual Account Group](/fx/api-reference/virtual-account-groups/get-group).

Unknown keys are rejected with `422 VALIDATION_ERROR`, and `validation_errors` names the offending key.

<ParamField body="business_legal_name" type="string" required>
  Registered legal name. Max 255 characters.
</ParamField>

<ParamField body="business_type" type="enum" required>
  Legal form of the business. One of `corporation`, `limited_liability_company`, `partnership`, `publicly_listed_company`, `trust`, `private_foundation`, `charity`, `non_profit_organization` or `public_agencies_or_authorities`; anything else returns `422`.
</ParamField>

<ParamField body="registered_address" type="object" required>
  Registered legal address. `address_line`, `city` and `country` are required; `country` must be an ISO 3166-1 alpha-2 code. `region` and `postal_code` are optional to Hop but commonly required by the provider.
</ParamField>

<ParamField body="business_registration_number" type="string" required>
  Official registration number, max 100 characters. For a US entity this is the EIN, which must be nine digits with or without the hyphen.
</ParamField>

<ParamField body="incorporation_date" type="string" required>
  Date of incorporation, ISO 8601.
</ParamField>

<ParamField body="operating_address_same_as_registered" type="boolean" default="true">
  Whether the business operates from its registered address. `operating_address` is required when this is `false`.
</ParamField>

<ParamField body="operating_address" type="object">
  Operating address, same shape as `registered_address`. Required when `operating_address_same_as_registered` is `false`.
</ParamField>

<ParamField body="business_industry" type="enum[]">
  One or more industry classifications. At least one is needed before a provider will approve onboarding.

  Unlike every other enum on this page, these values are capitalised display strings, spaces, slashes and all. Send them exactly as written:

  `Broker Dealer` · `Commodities Firm` · `Exchange` · `Family Office` · `Hedge Fund` · `Investment Advisor/Asset Manager` · `Loan/Finance Company` · `OTC Desk / Market Maker` · `Private Equity Fund` · `Special Purpose Vehicle` · `Third Party Payment Processor` · `Wealth Holding Vehicle` · `E-commerce Merchant` · `Marketplace Merchant` · `Gig Economy Platform` · `Operating Company (Other)`
</ParamField>

<ParamField body="expected_monthly_volume" type="enum">
  Expected monthly transaction volume band, in USD equivalent. One of:

  `from_0_to_10k` · `from_10k_to_50k` · `from_50k_to_100k` · `from_100k_to_1m` · `from_1m_to_10m` · `above_10m`
</ParamField>

<ParamField body="source_of_funds" type="enum">
  Primary source of the business's funds. One of:

  `commercial_activities` · `shareholder_capital` · `venture_capital` · `sale_of_assets` · `crypto_fundraising` · `crypto_trading_revenue` · `corporate_loans` · `other`
</ParamField>

<ParamField body="intended_use_of_account" type="enum">
  Primary intended use of the account. One of:

  `supplier_vendor_payments` · `intercompany_transfers` · `payroll` · `customer_payments_received` · `customer_payouts_refunds_settlements` · `operating_expenses` · `dividend_profit_distributions` · `loan_repayment_financial_activities`
</ParamField>

<ParamField body="is_regulated" type="boolean">
  Whether the business is regulated by a financial authority. When `true`, also send `regulator_information`, and upload the licence as a `regulatory_license` document with [Upload Document](/fx/api-reference/virtual-account-groups/upload-document).
</ParamField>

<ParamField body="regulator_information" type="object">
  The licence the business holds. Required for virtual account onboarding when `is_regulated` is `true`; until it is set, the group shows an `account_profile` requirement naming `regulator_information`. A patch replaces the whole object.

  <Expandable title="Regulator fields">
    <ParamField body="name" type="string" required>
      Name of the regulator, for example `FINRA` or `FCA`. 1 to 255 characters.
    </ParamField>

    <ParamField body="jurisdiction" type="string" required>
      ISO 3166-1 alpha-2 country where the licence is held.
    </ParamField>

    <ParamField body="register_number" type="string" required>
      Registration or licence number issued by the regulator. 1 to 100 characters.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="is_publicly_listed" type="boolean">
  Whether the business is listed on a stock exchange. Some US states require it for virtual account onboarding, so send it for every business.
</ParamField>

<ParamField body="public_listing" type="object">
  The exchange listing. Required for virtual account onboarding when `is_publicly_listed` is `true`; until it is set, the group shows an `account_profile` requirement naming `public_listing`. A patch replaces the whole object.

  <Expandable title="Listing fields">
    <ParamField body="exchange" type="string" required>
      Stock exchange where the business is listed, for example `NYSE`. 1 to 100 characters.
    </ParamField>

    <ParamField body="ticker_symbol" type="string" required>
      Ticker symbol on that exchange. 1 to 20 characters.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="business_operations_start_date" type="string">
  Date the business began operating, ISO 8601. Required by the provider.
</ParamField>

<ParamField body="tax_identification_number" type="string">
  Tax ID where it differs from the registration number. Max 100 characters. Required by the provider.
</ParamField>

<ParamField body="tax_residence_country_code" type="string">
  ISO 3166-1 alpha-2 country where the business is resident for tax. Needed before a group can be approved. It is not assumed from the country of incorporation or the registered address, so send it even when they match.
</ParamField>

<ParamField body="business_description" type="string">
  Free-text description of what the business does. Required by the provider.
</ParamField>

<ParamField body="website" type="string">
  Business website, max 500 characters. Required by the provider.
</ParamField>

<ParamField body="jurisdiction_of_incorporation" type="string">
  ISO 3166-1 alpha-2 country of incorporation.
</ParamField>

<ParamField body="email" type="string">
  Primary business contact email.
</ParamField>

### Individual fields: `type: "individual"`

Required on the first call: `first_name`, `last_name`, `email`, `date_of_birth`, `nationality` and `address`. `tax_identification` and the due-diligence fields below are optional to Hop but required by the provider, so supply them to avoid a round trip.

As with the business variant, unknown keys are rejected with `422 VALIDATION_ERROR`.

<ParamField body="first_name" type="string" required>
  Legal first name, 1 to 100 characters.
</ParamField>

<ParamField body="last_name" type="string" required>
  Legal last name, 1 to 100 characters.
</ParamField>

<ParamField body="middle_name" type="string">
  Middle name, 1 to 100 characters.
</ParamField>

<ParamField body="email" type="string" required>
  Email address.
</ParamField>

<ParamField body="date_of_birth" type="string" required>
  Date of birth, ISO 8601.
</ParamField>

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

<ParamField body="address" type="object" required>
  Residential address. `address_line`, `city` and `country` required, `country` as alpha-2. The provider requires `postal_code`, and `region` when the country is the United States.
</ParamField>

<ParamField body="phone_number" type="string">
  E.164 format, max 255 characters.
</ParamField>

<ParamField body="place_of_birth" type="string">
  City or locality of birth, 1 to 255 characters.
</ParamField>

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

<ParamField body="document_number" type="string">
  Government photo ID number, 1 to 255 characters.
</ParamField>

<ParamField body="tax_identification" type="object">
  Required by the provider. Both fields are mandatory within the object: `number` (1 to 255 characters) and `tax_residence_country_code` (alpha-2).
</ParamField>

#### Customer due diligence

Set each field on its own; a patch can send any of them. Until the provider's required ones are set, the group shows an `account_profile` requirement naming the missing fields.

<ParamField body="employment_status" type="enum">
  Required by the provider. One of `salaried` · `self_employed` · `unemployed` · `retired` · `student`
</ParamField>

<ParamField body="source_of_funds" type="enum">
  A different set from the business `source_of_funds` above. Required by the provider. One of:

  `salary` · `pension` · `savings` · `self_employment` · `crypto_trading` · `gambling` · `real_estate` · `gift` · `student_loan_grant`
</ParamField>

<ParamField body="intended_use_of_account" type="enum">
  A different set from the business `intended_use_of_account` above. Required by the provider. One of:

  `transfers_own_wallet` · `transfers_family_friends` · `investments` · `goods_services` · `donations`
</ParamField>

<ParamField body="pep_status" type="enum">
  Politically exposed person classification. Required by the provider. One of:

  `not_pep` · `former_pep_2_years` · `former_pep_older` · `domestic_pep` · `foreign_pep` · `close_associate` · `family_member`
</ParamField>

<ParamField body="expected_monthly_volume" type="object">
  Required in the EU. An object, not a band: `amount` (a positive decimal string, at most 2 decimal places) and `currency`; the one place the individual and business forms of this field differ.
</ParamField>

<ParamField body="estimated_yearly_income" type="enum">
  Required in the United States. 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`
</ParamField>

<ParamField body="employment_industry_sector" type="enum">
  Required in the United States. One of:

  `investment` · `hedge_fund` · `money_service_business` · `sto_issuer` · `precious_metals` · `non_profit` · `registered_investment_advisor` · `agriculture_forestry_fishing_hunting` · `mining` · `utilities` · `construction` · `manufacturing` · `wholesale_trade` · `retail_trade` · `transportation_warehousing` · `information` · `finance_insurance` · `real_estate_rental_leasing` · `professional_scientific_technical_services` · `management_of_companies_enterprises` · `administrative_support_waste_management_remediation_services` · `educational_services` · `health_care_social_assistance` · `arts_entertainment_recreation` · `accommodation_food_services` · `other_services` · `public_administration` · `not_classified` · `adult_entertainment` · `auctions` · `automobiles` · `blockchain` · `crypto` · `drugs` · `export_import` · `e_commerce` · `financial_institution` · `gambling` · `insurance` · `market_maker` · `shell_bank` · `travel_transport` · `weapons`
</ParamField>

<ParamField body="reference" type="string">
  Your own reference for this person, max 255 characters. Stored and echoed back.
</ParamField>

## Response

Returns `200` with the account, in the same shape as [Get Account](/fx/api-reference/accounts/get-account). The stored profile is echoed in `profile`, and the identity fields projected onto the account itself, `legal_name`, `business_registration_number`, `address`, `type`, reflect the merge.

A patch that changes nothing returns the account unchanged.

## Errors

| Status | `code` | When |
| - | - | - |
| `422` | `VALIDATION_ERROR` | The merged profile is incomplete or invalid, including a first call that omits a required field. `details.errors` names each offending field |
| `422` | `VALIDATION_ERROR` | `type` does not match the stored profile type. `details` carry both values |
| `422` | `VALIDATION_ERROR` | A field is individually malformed: a country code that is not alpha-2, a phone that is not E.164, an invalid email, or an unknown key on an individual profile |
| `422` | `INVALID_FIELD_FORMAT` | `business_registration_number` is not an EIN although `registered_address.country` or `jurisdiction_of_incorporation` is `US`: nine digits, with or without the hyphen. `details` carry `field` and `expected_format` |
| `403` | `ACCESS_DENIED` | The account exists but belongs to another organization |
| `404` | `RESOURCE_NOT_FOUND` | `account_id` is unknown or deleted |

## Request Example

```json Business theme={null}
{
  "type": "business",
  "business_legal_name": "Acme Pte Ltd",
  "business_type": "limited_liability_company",
  "business_registration_number": "200912345A",
  "incorporation_date": "2009-04-17",
  "registered_address": {
    "address_line": "10 Marina Boulevard, #23-01",
    "city": "Singapore",
    "region": "Central Region",
    "postal_code": "018983",
    "country": "SG"
  },
  "business_operations_start_date": "2009-06-01",
  "tax_identification_number": "200912345A",
  "tax_residence_country_code": "SG",
  "business_description": "Cross-border payouts for marketplace sellers",
  "website": "https://acme.example",
  "is_regulated": false
}
```

```json Individual theme={null}
{
  "type": "individual",
  "first_name": "Jane",
  "last_name": "Mueller",
  "email": "jane@example.com",
  "date_of_birth": "1988-02-11",
  "nationality": "DE",
  "birth_country_code": "DE",
  "address": {
    "address_line": "Friedrichstrasse 43",
    "city": "Berlin",
    "postal_code": "10117",
    "country": "DE"
  },
  "tax_identification": {
    "number": "12345678901",
    "tax_residence_country_code": "DE"
  },
  "employment_status": "salaried",
  "source_of_funds": "salary",
  "intended_use_of_account": "transfers_own_wallet",
  "pep_status": "not_pep",
  "expected_monthly_volume": {"amount": "5000.00", "currency": "EUR"}
}
```

## Next steps

For a **business** account, add at least one [associated person](/fx/api-reference/associated-persons/create-associated-person) with `is_signer: true`. A business cannot complete its provider agreements without one. An **individual** account needs none.

Then open the group with [Create Virtual Account Group](/fx/api-reference/virtual-account-groups/create-group), or let an already-open group resume on its own.