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

# End-Customer Verification (KYB)

> How end-customer accounts are verified — requirements, status lifecycle, and tracking review progress

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.

<Note>
  **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.
</Note>

## Status lifecycle

Verification review starts automatically once all requirements are complete. Track progress through `kyc_status` on the account:

| Status          | Meaning                                                                                                 | What you do                                                                                                                                 |
| --------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `not_started`   | The account exists, but requirements are not complete or review has not started.                        | Use GET Account to inspect missing requirements, upload company documents, add/verify associated persons, and complete required agreements. |
| `under_review`  | All requirements were completed and the account is in verification review.                              | Wait; no action required unless the status moves to `action_needed`.                                                                        |
| `action_needed` | Verification review needs more data, corrected data, more documents, or associated-person verification. | Fix the missing/issue items shown by GET Account.                                                                                           |
| `approved`      | Verification passed. The account is ready to operate.                                                   | Proceed — virtual accounts, deposits, and payments.                                                                                         |
| `rejected`      | Verification failed. Terminal — the account cannot be edited or resubmitted.                            | Review `rejection_reasons`; contact support if you believe this is in error.                                                                |

<Note>
  `approved` and `rejected` are terminal — Update Account and associated-person updates are blocked once a terminal status is reached.
</Note>

## Tracking review progress

You have two options — and you do not need to poll:

<ResponseField name="account.updated webhook" type="recommended">
  Fires on every KYB status transition. The payload is the full account object — the same shape as Get Account. See Webhook Event Catalog.
</ResponseField>

<ResponseField name="GET Account">
  Read `kyc_status` on demand, plus the detail fields below.
</ResponseField>

The account object breaks onboarding and review down further:

<ResponseField name="onboarding">
  Readiness metadata: `ready_for_submission`, `submission_status` (`not_ready` | `ready` | `submitting` | `submitted`), and `requirements_version`.
</ResponseField>

<ResponseField name="requirements">
  Requirement state across company fields, company documents, associated-person role counts, hosted verification, and agreements.
</ResponseField>

<ResponseField name="rejection_reasons">
  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.
</ResponseField>

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