Skip to main content
PATCH
Update Account
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

​
string
required
The customer’s external ID (starts with cus_)
​
string
required
The account’s external ID (starts with acct_)
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

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

​
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. Unknown keys are rejected with 422 VALIDATION_ERROR, and validation_errors names the offending key.
​
string
required
Registered legal name. Max 255 characters.
​
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.
​
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.
​
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.
​
string
required
Date of incorporation, ISO 8601.
​
boolean
default:"true"
Whether the business operates from its registered address. operating_address is required when this is false.
​
object
Operating address, same shape as registered_address. Required when operating_address_same_as_registered is false.
​
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)
​
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
​
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
​
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
​
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.
​
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.
​
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.
​
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.
​
string
Date the business began operating, ISO 8601. Required by the provider.
​
string
Tax ID where it differs from the registration number. Max 100 characters. Required by the provider.
​
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.
​
string
Free-text description of what the business does. Required by the provider.
​
string
Business website, max 500 characters. Required by the provider.
​
string
ISO 3166-1 alpha-2 country of incorporation.
​
string
Primary business contact email.

​
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.
​
string
required
Legal first name, 1 to 100 characters.
​
string
required
Legal last name, 1 to 100 characters.
​
string
Middle name, 1 to 100 characters.
​
string
required
Email address.
​
string
required
Date of birth, ISO 8601.
​
string
required
ISO 3166-1 alpha-2 nationality.
​
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.
​
string
E.164 format, max 255 characters.
​
string
City or locality of birth, 1 to 255 characters.
​
string
ISO 3166-1 alpha-2 country of birth. Required by the provider.
​
string
Government photo ID number, 1 to 255 characters.
​
object
Required by the provider. Both fields are mandatory within the object: number (1 to 255 characters) and tax_residence_country_code (alpha-2).

​
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.
​
enum
Required by the provider. One of salaried · self_employed · unemployed · retired · student
​
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
​
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
​
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
​
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.
​
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
​
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
​
string
Your own reference for this person, max 255 characters. Stored and echoed back.

​
Response

Returns 200 with the account, in the same shape as 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

​
Request Example

Business
Individual

​
Next steps

For a business account, add at least one 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, or let an already-open group resume on its own.