Skip to main content
There are two layers of verification. Your organization (the Platform customer) is verified by Hop during commercial onboarding — that happens outside this API. Your end customers (accounts) are verified through this API, and this section explains how.

​
KYB completes automatically when requirements are ready

There is no separate “submit KYB” endpoint. Create Account creates the end-customer account and fixes the set of KYB requirements it must satisfy — read them back with Get Account. Completion is data-driven: once required fields, company documents, and associated-person verification are satisfied, Hop starts verification review automatically.

​
Business profile

Legal name, business type enum, industry, country of incorporation, registration/tax identifiers, registered and operating addresses, website or business description, source of funds, purpose of account, and expected deposit/withdrawal volume buckets.

​
Documents

Entity (business) documents are uploaded only through the Upload Account Document endpoint after account creation. Uploaded files are held securely by Hop in the staged state and move to submitted when verification review starts. An associated person’s identity documents are captured inside their Verification Session, not uploaded through the API.

​
Associated persons

UBOs, directors, control persons, partners where applicable, and authorized signatories. Authorized signatory status is represented by is_signer=true. ownership_percentage is required for ultimate beneficial owners. Each person carries their own verification_status and hosted verification-session state.
Agreements are account-scoped Hop records. Agreements are independent account-scoped actions accepted by an authorized signer; they are not part of the automatic KYB submission readiness (they gate account activation separately). Use the Agreements endpoints to list assigned agreements, fetch content, and record accept/reject actions.

​
Status lifecycle

Verification review starts automatically once all requirements are complete. Track progress through kyc_status on the account:
approved and rejected are terminal — Update Account and associated-person updates are blocked once a terminal status is reached.

​
Tracking review progress

You have two options — and you do not need to poll:
​
recommended
Fires on every KYB status transition. The payload is the full account object — the same shape as Get Account. See Webhook Event Catalog.
​
Read kyc_status on demand, plus the detail fields below.
The account object breaks onboarding and review down further:
​
Readiness metadata: ready_for_submission, submission_status (not_ready | ready | submitting | submitted), and requirements_version.
​
Requirement state across company fields, company documents, associated-person role counts, hosted verification, and agreements.
​
Populated only when kyc_status is rejected (terminal); each entry carries a user-safe reason and an engineering-facing developer_reason. Null otherwise. Recoverable review requests (action_needed) surface under requirements.issues instead.

​
Completing requirements or fixing action_needed

When the status is not_started or action_needed, read requirements.missing, requirements.issues, and associated_persons[] to see what is needed, then:
  1. Correct business fields with Update Account, and supply entity documents with Upload Account Document (each upload claims a requirement_key from the lists above). Your own writes do not fire account.updated — re-fetch Get Account to see requirements progress; the webhook fires when Hop changes the verification state.
  2. Correct people with Update Associated Person, or add missing ones with Create Associated Person. For identity verification, create a Verification Session for the person and share the returned link.
  3. Accept required agreements with an authorized signer. When all requirements pass, Hop starts verification review automatically; when review begins or the status changes, you will receive the next account.updated event.