HIFI Docs

Some business users require their Ultimate Beneficial Owners (UBOs) to complete a liveness check before USD virtual accounts can be enabled.

Complete the normal KYB submission first. See Liveness Checks for the countries and ownership threshold that require this flow.

How It Works

Check the business status

Call the KYC Status API after submitting KYB.

Find incomplete UBOs

Look for UBOs with status: "INCOMPLETE" and a liveness URL.

Show each UBO their link

Send the corresponding liveness URL to the UBO. Sumsub handles the hosted verification flow.

Wait for completion

Continue checking the business status until no required UBO remains incomplete, then wait for HIFI to enable virtual accounts for the profile.

Check the Business Status

Call Retrieve KYC Status for the USD rail.

curl --request GET \
  --url "https://sandbox.hifibridge.com/v2/users/USER_ID/kyc/status?rails=USD" \
  --header "accept: application/json" \
  --header "authorization: Bearer YOUR_API_KEY"

When liveness checks are outstanding, the response includes:

A top-level status of PENDING
NOT_ALL_CHECKS_COMPLETED in reviewResult.rejectReasons
An INCOMPLETE UBO with a liveness URL

View relevant response fields

{
  "status": "PENDING",
  "reviewResult": {
    "reviewAnswer": "APPROVED",
    "rejectReasons": ["NOT_ALL_CHECKS_COMPLETED"]
  },
  "details": {
    "ultimateBeneficialOwners": {
      "details": [
        {
          "id": "33673710-8cd7-407b-81a3-01f105970baf",
          "status": "INCOMPLETE",
          "message": "Please complete [selfie, phone_verification].",
          "liveness": "https://in.sumsub.com/websdk/p/sbx_BsHt7ee3DsGcSsSi"
        }
      ]
    }
  }
}

Use the top-level status as the completion signal. A reviewAnswer of APPROVED does not mean the business is ready while status is PENDING.

Show Each UBO Their Link

Inspect every item in details.ultimateBeneficialOwners.details. For each incomplete UBO with a liveness URL, show the API message and a link to the hosted flow.

const owners =
  status.details?.ultimateBeneficialOwners?.details ?? [];

const incompleteOwners = owners.filter(
  (owner) => owner.status === "INCOMPLETE" && owner.liveness
);

return incompleteOwners.map((owner) => (
  <section key={owner.id}>
    <p>{owner.message}</p>
    <a href={owner.liveness}>Complete verification</a>
  </section>
));

Each UBO has their own liveness URL. Show the URL only to the corresponding UBO, and do not construct or modify it.

Wait for Virtual Account Enablement

After the UBO completes the Sumsub flow, continue calling Retrieve KYC Status. Keep the business pending while any UBO is INCOMPLETE or the response includes NOT_ALL_CHECKS_COMPLETED. Do not attempt to create a virtual account while a required UBO remains incomplete. A top-level status of ACTIVE confirms that the compliance review is complete; virtual-account availability is enabled for the profile by HIFI.

Guides

Recipes

Liveness Checks

How It Works

Check the Business Status

Show Each UBO Their Link

Wait for Virtual Account Enablement

​How It Works

​Check the Business Status

​Show Each UBO Their Link

​Wait for Virtual Account Enablement

​Related Pages

How It Works

Check the Business Status

Show Each UBO Their Link

Wait for Virtual Account Enablement

Related Pages