Skip to main content
This section covers how to onboard individual users onto the platform. The onboarding flow includes creating the user, completing the required KYC processes, and confirming the user’s capabilities are unlocked before they transact.

​
The onboarding flow

  1. Create the user — fetch the applicable Terms of Service, present them to the user, and register them via POST /core/users.
  2. Complete KYC processes — collect and submit the required verification data. The required processes are determined by the Terms of Service the user accepted at registration.
  3. Verify capabilities — once the required KYC processes pass, confirm the user’s capabilities are enabled and they are ready to transact.

​
Terms of service

To create a user, they must first accept the general terms applicable to their country of residence. The accepted terms determine which KYC processes are required for that user — each column in the matrix below corresponds to a specific terms variant.

​
KYC processes

The required processes () are determined by the Terms of Service the user accepted at registration. Processes marked as conditional () are triggered by specific circumstances described below.
Process \ ToSgeneral-gb-fcageneral-us-hqgeneral-pt-bopgeneral-bs-scb
email
phone
profile
address
identity
proofOfAddress
customerDueDiligence
enhancedDueDiligence
cryptoRiskAssessment
selfCategorizationStatement
taxDetails
KYC requirements vary by partner configuration and regulatory interpretation. The table above reflects Uphold’s baseline requirements — consult your Account Manager for specifics applicable to your integration.
proofOfAddress may automatically transition to ok without a submission. This happens when the address can be resolved from another process — for example, when the identity document submitted during the identity process contains address data. Always check the proofOfAddress status after completing identity before prompting the user to provide a document.
customerDueDiligence is required for all users except those under general-us-hq, where it is only enforced when the user makes a crypto deposit or withdrawal.
enhancedDueDiligence starts as exempt for all users. It is triggered automatically when customerDueDiligence results in a high-risk score — its status then moves from exempt to pending and the user must provide source-of-funds documentation (e.g. pay stubs, bank statements, or portfolio statements).Users under general-us-hq are permanently exempt from enhancedDueDiligence. Instead, they receive additional questions within the customerDueDiligence form when a high-risk score is reached.
taxDetails is required for users under general-gb-fca, general-us-hq, and general-pt-bop. For general-bs-scb, it is only required if the user is a US citizen — in all other cases it remains exempt.
Some processes have dependencies that must be satisfied before submission:
  • Submit profile before identity — identity verification depends on profile data
  • Submit profile and address before proofOfAddress
  • enhancedDueDiligence is only triggered after customerDueDiligence returns a high-risk score — submit it only when prompted
  • All other processes can be submitted in any order or in parallel
Some processes require periodic re-verification. When a review is due, the process status reverts to pending and the user must resubmit information.Processes subject to periodic review:
  • profile — user confirms their information is still accurate
  • address — user confirms their address is still accurate
  • identity — user submits an updated document when the current one is approaching expiration
  • customerDueDiligence — user redoes the questionnaire after a set period
  • selfCategorizationStatement — user redoes the form after a set period (GB only)
Monitor via core.kyc.*.status-changed webhooks to catch these transitions in real time.

​
Verification model

For each KYC process, there is an authoritative party responsible for verifying the data — either Uphold or your organization. Some processes support both models. For example, email and phone are always verified by your organization, while taxDetails is always verified by Uphold. Processes like customerDueDiligence support either party depending on your setup. See the KYC introduction for the full authoritativeness reference.

​
Integration approaches

There are three ways to implement individual user onboarding. The REST API and KYC Connector are complementary — you can use the KYC Connector for document-heavy processes and the REST API for the rest.

Via REST API

  • You want to maintain control over the UI
  • You have specific branding requirements
  • You need a deep system integration

Via KYC Connector

  • You want to maintain control over the UI
  • You already use Sumsub or Veriff
  • You don’t want to modify your existing onboarding flows

Via KYC Widget

  • You’re comfortable with a managed UI
  • You need the fastest time-to-market
  • You have limited development resources

​
Best practices

Progressive onboarding

Don’t request all information upfront. Start with basic processes (email, phone, profile, address) and prompt for sensitive documents only when the user’s intended actions require them.

Clear document guidelines

Before the user submits identity or proof-of-address documents, show clear requirements: accepted document types, file format, resolution, and recency limits. This significantly reduces verification failures and re-submission cycles.