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

# KYB API introduction

> Manage KYB processes on the Uphold platform to keep business users compliant with regulatory requirements. Learn the process model, statuses, associated persons, and the attestation flow.

The KYB group of endpoints allows you to manage the Know Your Business processes available on the platform, ensuring that your business users are compliant with regulatory requirements.

KYB applies exclusively to users created with `type: business` through the [Create user](../users/create-user) endpoint. Individual users are onboarded through the [KYC](../kyc/introduction) endpoints instead.

<Note>The KYB endpoints are in **preview**. None of them are available in **Production** yet, and only some are available in **Sandbox** — each endpoint page states its own availability.</Note>

## How it's designed

Every KYB process has four fundamental properties:

* `code`: A unique identifier for the process.
* `status`: As the name implies, this is the status of the process.
* `input`: The data provided by your organization when completing the process.
* `output`: The data that came out of verifying the input, present only on processes that produce a verification result.

### Statuses

The `status` field can have the following values:

* `pending`: The process is pending information.
* `running`: The process is currently being verified.
* `ok`: The process has been successfully verified.
* `failed`: The process has failed verification.
* `exempt`: The process is exempt from verification.

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

## KYB processes

### List of processes

* [`profile`](./update-profile): Process associated with the business's own information, such as legal entity name, formation date, industry, legal identifiers, and addresses.
* [`documents`](./update-documents): Process associated with the corporate documents evidencing the business's incorporation, ownership, control, standing, and tax identity.
* [`associatedPersons`](./associated-persons/list-associated-persons): Process associated with the individuals tied to the business, such as beneficial owners and authorized signers. Each person carries their own set of processes:
  * [`profile`](./associated-persons/update-profile): The person's identifying information.
  * [`identity`](./associated-persons/update-identity): Identity verification to prove the person is who they claim to be.
  * [`proofOfAddress`](./associated-persons/update-proof-of-address): Address verification to prove the person lives where they claim to live.
* [`financialInstitution`](./update-financial-institution): Process associated with the regulatory information required from businesses operating in the `financial-institutions-and-money-services` industry sector. It is `exempt` for every other sector.
* [`attestation`](./trigger-attestation): Background process that runs the verification checks over everything the business submitted, producing the final KYB decision.

### File-based processes

The `documents` and `financialInstitution` processes, as well as the `identity` and `proofOfAddress` processes of each associated person, are completed by referencing previously uploaded files.

To complete a file-based process:

1. **Create the file** — call [Create file](../files/create-file) with the `document` category. Use the returned `upload` object to upload the file directly to the storage provider.
2. **Submit the process** — call the corresponding endpoint referencing the file `id`.

<Warning>Every KYB file must belong to the `document` category. Referencing a file from another category fails with `file_invalid`, and referencing a file that was created but never uploaded fails with the same code.</Warning>

## Associated persons

Associated persons are the individuals the platform must know about in order to verify the business. Each person is created with a `type`:

* `beneficial-owner`: An individual who ultimately owns or controls a share of the business. Supports `ownershipPercentage`.
* `authorized-signer`: An individual authorized to act on behalf of the business.
* `beneficial-owner-and-authorized-signer`: An individual who is both. Supports `ownershipPercentage`.

Every associated person carries three processes of their own, each with the same `code`/`status`/`input`/`output` shape as the business-level processes:

* [`profile`](./associated-persons/update-profile): The person's name, role, date and place of birth, address, legal identifiers, and ownership percentage.
* [`identity`](./associated-persons/update-identity): Identity verification through a government-issued document.
* [`proofOfAddress`](./associated-persons/update-proof-of-address): Address verification through a supporting document.

The `identity` and `proofOfAddress` processes expose an extra `type` field indicating how they are being completed: `none` while nothing has been submitted, or `document-submission` once documents have been provided.

<Tip>The `associatedPersons` process aggregates the status of every person. It only reaches `ok` once all of them have completed their own processes.</Tip>

## Attestation

The `attestation` process is the final step of KYB. It does not accept input — you [trigger](./trigger-attestation) it once the business has submitted everything else, and Uphold runs a set of checks that populate `output.checks`.

Each check exposes a `code`, a `status` (`not-started`, `skipped`, `in-progress`, `in-review`, `approved`, or `rejected`), and optionally a `reason` and a `note` explaining the result.

If the attestation process fails, you should consult the checks to understand what went wrong and how you or the end-user can fix it. Once the attestation process succeeds, the business is considered verified and compliant with regulatory requirements.

## Webhooks

Subscribe to webhooks to be notified as the processes progress:

* `core.kyb.{process}.status-changed`: a business-level process changed status.
* `core.kyb.associated-person.created` and `core.kyb.associated-person.deleted`: an associated person was added or removed.
* `core.kyb.associated-person.{process}.status-changed`: a process of a specific associated person changed status. The payload includes `associatedPersonId`.

See [Webhooks](../../webhooks) for delivery, retries, and signature verification.