Skip to main content
The KYC group of endpoints allows you to manage KYC processes available on the platform, ensuring that your users are compliant with regulatory requirements.

​
How it’s designed

Every KYC is designed as a process that has five fundamental properties:
  • code: A unique identifier for the process.
  • status: As the name implies, this is the status of the process.
  • verification: An object describing how the process should be completed, including who is responsible for verification, how the process is driven, and any dependencies on other processes.
  • input: The input is data provided by the user when prompted to complete the process.
  • output: The output is data that came out from verifying the input data provided by the user.

​
Statuses

The status field can have the following values:
  • exempt: The process is exempt from verification.
  • pending: The process is pending information from the user.
  • processing: The process is currently being verified.
  • ok: The process has been successfully verified.
  • failed: The process has failed verification.
You may subscribe to webhooks for when the status of a KYC process changes.

​
Verification

Every KYC process exposes a verification object that describes how it must be completed for the current user and organization: 
{
  "verification": {
    "model": "partner-verified",
    "method": "manual",
    "dependencies": ["phone", "profile", "address"]
  }
}
  • model: who is responsible for verifying the data.
    • uphold-verified: Uphold always produces the output. Depending on the process, verification is either driven by a third-party provider session (no explicit update possible) or by input submitted by your organization.
    • partner-verified: Your organization always produces both input and output, performing the verification directly and typically resulting in immediate ok status.
  • method: whether the process requires explicit input or advances automatically.
    • manual: requires explicit input from the user or your organization (e.g., form answers, documents, or direct data submission).
    • automatic: Uphold runs this without user input, triggered automatically when the processes listed in triggers complete.
  • triggers: the list of processes whose completion causes this process to run automatically. Only present when method is automatic and at least one trigger is defined.
  • dependencies: the list of processes that must be completed before this process can be submitted. Only present when the process has at least one prerequisite.

​
KYC processes

​
List of processes

  • email: Process associated with updating the user’s email.
  • phone: Process associated with updating the user’s phone number.
  • profile: Process associated with updating the user’s basic information, such as name, date of birth and citizenship.
  • address: Process associated with updating the user’s address of residence.
  • identity: Process associated with updating the user’s identity, usually through a government-issued ID.
  • proofOfAddress: Process associated with updating the user’s proof-of-address, usually through a utility bill or bank statement.
  • customerDueDiligence: Process associated with performing due diligence on the customer, ensuring compliance with regulatory requirements.
  • enhancedDueDiligence: Process associated with providing proof after completing the customerDueDiligence process that is needed in certain high-risk scenarios.
  • cryptoRiskAssessment: Process associated with performing analysis on the user’s knowledge about crypto and associated risks (GB residents only).
  • selfCategorizationStatement: Process associated with identifying the user’s investor profile, including risk level and investment preferences (GB residents only).
  • taxDetails: Process associated with collecting and verifying the user’s tax-related information.
  • screening: Background process associated with checking user provided data against official lists of sanctioned parties.
  • risk: Background process associated with checking user provided data and activity patterns.

​
Form-based processes

Some processes, such as profile, customerDueDiligence and taxDetails, are composed of a form with questions the user must answer. For these types of processes, you get a hint property which includes a JSON Schema and UI Schema that define the form structure. To complete a form-based process:
  1. Fetch the form schema — call Get KYC Overview with ?detailed={process} to retrieve the hint.
  2. Render the form — use the hint to display the current questions. See Dynamic Forms for rendering guidance.
  3. Submit answers — call PATCH /core/kyc/processes/{process} with input.formId and input.answers.
  4. Repeat — continue until status leaves pending and output is correctly populated.
Forms are progressive — answers to one question may change which questions follow. Never hardcode the question set; always re-fetch the hint after each submission.
When a form-based process is partner-verified for your organization, skip the form cycle — collect the data through your own means, then submit both input and output in a single PATCH. The process transitions to ok immediately.

​
File-based processes

Some processes, such as identity, proofOfAddress and enhancedDueDiligence, require users to upload necessary documents to complete the verification. To complete a file-based process:
  1. Create the file — call Create File for each document. Use the returned upload object to upload the file directly to the storage provider.
  2. Submit the process — call PATCH /core/kyc/processes/{process} referencing the file id in input.media.
You can look up the exact file categories each KYC process requires by checking the documentation for each endpoint.

​
Background processes

There are background processes, such as screening and risk, that happen behind the scenes as the user provides data in other KYC processes and engages in activities on the platform, such as transactions. There are no associated endpoints to update these processes, since their underlying verification is based on internal monitoring done by Uphold.

​
Periodic review

Some processes require periodic review, in which their status may change to pending, signaling that the user must provide updated information.
  • profile: The user must confirm their profile information is still accurate.
  • address: The user must confirm their address is still accurate.
  • identity: The user must provide up-to-date identity when their underlying document is about to expire.
  • customerDueDiligence: The user must redo the form after a certain period of time.
  • selfCategorizationStatement: The user must redo the form after a certain period of time.