> ## Documentation Index
> Fetch the complete documentation index at: https://developer.uphold.com/llms.txt
> Use this file to discover all available pages before exploring further.

# KYC API introduction

> Manage KYC processes on the Uphold platform to keep users compliant with regulatory requirements. Learn the process model, statuses, and verification flow.

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.

<Tip>You may subscribe to [webhooks](./webhooks) for when the status of a KYC process changes.</Tip>

### Verification

Every KYC process exposes a `verification` object that describes how it must be completed for the current user and organization:

```json theme={null}
{
  "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.
* `rules`: only present on some processes — a per-field map describing each field's `presence` (`required`/`optional`/`disallowed`) and whether it is still `editable` for the current user.

## KYC processes

### List of processes

* [`email`](./update-email): Process associated with updating the user's email.
* [`phone`](./update-phone): Process associated with updating the user's phone number.
* [`profile`](./update-profile): Process associated with updating the user's personal information, such as name, date of birth, citizenship, and residential address.
* [`identity`](./update-identity): Process associated with updating the user's identity, usually through a government-issued ID.
* [`proofOfAddress`](./update-proof-of-address): Process associated with updating the user's proof-of-address, usually through a utility bill or bank statement.
* [`customerDueDiligence`](./update-customer-due-diligence): Process associated with performing due diligence on the customer, ensuring compliance with regulatory requirements.
* [`enhancedDueDiligence`](./update-enhanced-due-diligence): Process associated with providing proof after completing the `customerDueDiligence` process that is needed in certain high-risk scenarios.
* [`cryptoRiskAssessment`](./update-crypto-risk-assessment): Process associated with performing analysis on the user's knowledge about crypto and associated risks (`GB` residents only).
* [`selfCategorizationStatement`](./update-self-categorization-statement): Process associated with identifying the user's investor profile, including risk level and investment preferences (`GB` residents only).
* [`taxDetails`](./update-tax-details): 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 `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](./get-overview) with `?detailed={process}` to retrieve the `hint`.
2. **Render the form** — use the hint to display the current questions. See [Dynamic Forms](/developer-guides/resources/dynamic-forms/introduction) 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.

<Info>
  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.
</Info>

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](../files/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, including their residential address, is still accurate.The user must confirm their profile information 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.