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 three fundamental properties:
  • status: As the name implies, this is the status of the process.
  • 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.
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.

​
Authoritativeness

For each KYC process, there’s an authoritative party, which can either be Uphold or your organization. If the authoritative party is Uphold, your organization is only responsible for collecting the user’s information (input) and Uphold is responsible for verifying it and producing an outcome (output).
If the authoritative party is your organization, then you are responsible for collecting the user’s information (input) and verifying it, producing an outcome (output). Whether your organization is authoritative or not in a specific KYC process depends on how you perform the verification, and whether Uphold’s legal and compliance teams have approved it.
Even though your organization may be authoritative in certain KYC process, Uphold can reject your updates in some cases. As an example, Uphold will reject an update to a user’s identity that refers to a passport already associated to another user.

​
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.
If your organization is the authoritative party for a form-based process, 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.