Accounts
Create Account
Create an account and start verification — a draft KYB application for businesses, or a complete KYC submission for individuals
POST
Accounts represent the Platform end customers you onboard under your Platform customer.
Business fields —
Business creation opens a draft — the account starts as
Individual fields —
For individuals, create is the submission: the profile must be complete in this request, and the account starts as
type selects the flow. For business accounts, creation opens a draft KYB application: business details and optional associated persons are captured first, company documents are uploaded separately via the Documents endpoints, and Hop starts verification review automatically once the requirements returned by Get Account are complete. For individual accounts, create is the submission: the full profile is captured in this request, the account starts as under_review, and only the account holder’s hosted verification session remains. Account routes are customer-scoped (/customers/{customer_id}/accounts); the {customer_id} must be your own customer id.
The call is idempotent on (customer, Idempotency-Key); re-using the same key returns the existing account instead of creating a duplicate. Documents are not accepted in this request — business documents go through Upload Account Document, and individual identity documents are captured in the hosted verification session.
Path Parameters
string
required
Platform customer id (e.g.
cus_x7k2m9p4q1w8e5r3t6y0u2i4).Headers
string
required
Unique key for this create. Re-using a key for the same customer returns the previously created account.
Request Body
enum
required
Entity type:
business or individual. Selects the verification flow — KYB for businesses, KYC for individuals — and which field group below applies.Business fields — type: "business"
Business creation opens a draft — the account starts as kyc_status: not_started. Complete the remaining requirements (documents, associated persons) after create, and Hop submits automatically.
string
required
Legal name of the business. Max 255 characters.
string
required
Business structure (e.g.
private_limited_company, corporation, partnership, llc). Free-form string; not restricted to a fixed enum yet.enum[]
required
Industry classifications used for verification and risk review. Each item must be one of:
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, or Operating Company (Other). Wealth Holding Vehicle, E-commerce Merchant, and Marketplace Merchant are three separate values.string
required
Business registration number issued by the country of incorporation. Max 100 characters.
Address
required
Registered legal address of the business. The Address object is shared: it is used for KYB addresses, associated-person residential addresses, beneficiary addresses, bank addresses, and correspondent-bank addresses.
boolean
default:"true"
Whether the operating address is the same as
registered_address. Defaults to true when omitted. When false, operating_address is required.Address | null
Conditional. Operating address. Required when
operating_address_same_as_registered is false; otherwise use null. Same shape as registered_address.string
Tax ID / TIN / UEN. Optional — provide only when it differs from
business_registration_number.date
required
Date of incorporation, ISO 8601 (e.g.
2018-04-01).string | null
Optional override for the incorporation country (ISO 3166-1 alpha-2). Defaults to
registered_address.country; send only when the incorporation country differs from the registered address country.string | null
Conditional. Free-text description of the business. Required when
website is not provided.string | null
Primary business contact email.
string | null
Conditional. Business website. At least one of
website or business_description must be provided; when the business has no website, business_description is required.string[]
required
Sources of funds (e.g. revenues, investor funds, loan, personal savings, sale of business or real estate, investments, other). At least one value.
string | null
Expected monthly deposit volume bucket.
string | null
Expected monthly withdrawal volume bucket.
string[]
required
Purposes of the account (e.g. payments to vendors, suppliers, customers, utilities, tax, inter-company transfers, receipts from clients or government). At least one value.
object[] | null
Optional inline UBOs, directors and control persons (a partner is classified by the role they actually hold; signing authority is the
is_signer flag, not a role). Same shape as the create body in the Associated Persons section; persons can also be added later via the dedicated endpoints.Individual fields — type: "individual"
For individuals, create is the submission: the profile must be complete in this request, and the account starts as under_review. The only remaining step is the account holder’s hosted verification session (identity document + selfie) — there is no document upload and no associated persons. Unknown fields are rejected.
The cdd object takes values from these closed sets:
string
required
Legal first name. Max 100 characters.
string | null
Middle name. Max 100 characters.
string
required
Legal last name. Max 100 characters.
string
required
Email address of the account holder.
string | null
Phone number in E.164 international format (e.g.
+6591234567).string | null
Additional notes or a description of this individual customer. Max 255 characters.
date
required
Date of birth, ISO 8601 (e.g.
1990-06-15).string | null
Place of birth (city or locality). Max 255 characters.
string
required
Government-issued photo identification document number. The document itself is captured in the hosted verification session.
string
required
Nationality, ISO 3166-1 alpha-2 (validated).
Address
required
Residential address. Same shared Address shape as
registered_address; country must be a valid ISO 3166-1 alpha-2 code.object | null
Tax identification details — required where applicable: SSN/ITIN for US residents, the local tax number elsewhere.
object
required
Customer Due Diligence details. All four fields take values from the closed sets in the table above.
string | null
Client-defined reference for the individual in an external system. Stored and echoed back; not a lookup key. Max 255 characters.
Response
Returns 200 with the new account’sid and initial onboarding status. For business accounts, KYB review does not start until the requirements returned by Get Account are complete; Hop then starts verification review automatically. Individual accounts start as under_review — the create request is the submission, and only the hosted verification session remains.
Supporting documents are supplied after the account is created: entity (business) documents via Upload Account Document, and each associated person’s identity documents inside their Verification Session. For individual accounts, the account holder’s identity document and selfie are captured inside their hosted verification session — there is no document upload.
string
Account id (e.g.
acct_3mnq7c1e6a2b4f3c9b8d2e5a).enum
Verification status:
not_started, under_review, action_needed, approved, or rejected. Business accounts start as not_started; individual accounts start as under_review.