Skip to main content
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 endpoint. Individual users are onboarded through the KYC endpoints instead.
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.

​
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.
You may subscribe to webhooks for when the status of a KYB process changes.

​
KYB processes

​
List of processes

  • profile: Process associated with the business’s own information, such as legal entity name, formation date, industry, legal identifiers, and addresses.
  • documents: Process associated with the corporate documents evidencing the business’s incorporation, ownership, control, standing, and tax identity.
  • associatedPersons: 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: The person’s identifying information.
    • identity: Identity verification to prove the person is who they claim to be.
    • proofOfAddress: Address verification to prove the person lives where they claim to live.
  • financialInstitution: 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: 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 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.
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.

​
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: The person’s name, role, date and place of birth, address, legal identifiers, and ownership percentage.
  • identity: Identity verification through a government-issued document.
  • proofOfAddress: 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.
The associatedPersons process aggregates the status of every person. It only reaches ok once all of them have completed their own processes.

​
Attestation

The attestation process is the final step of KYB. It does not accept input — you trigger 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 for delivery, retries, and signature verification.