Verify a Business Customer with KYB

Overview

KYB (Know Your Business) verifies the identity of your business customers. Unlike individual KYC verification, KYB requires verifying both the business entity and its Ultimate Beneficial Owners (UBOs).

This guide walks you through the complete KYB workflow using Persona.

Prerequisites

Active Cybrid organization and bank account with Persona integration enabled
API credentials with permission to create customers and identity verifications
Frontend integration capability for Persona SDK or web redirect

Create a business customer

Create a customer with type: business.

POST /api/customers
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "type": "business"
}

{
  "created_at": "2026-01-21T21:37:23.172157Z",
  "updated_at": "2026-01-21T21:37:23.172157Z",
  "guid": "customer_guid",
  "bank_guid": "bank_guid",
  "type": "business",
  "state": "storing",
  "labels": null,
  "compliance_decisions": [],
  "activity_limits": []
}

Poll for customer state

The customer state progresses from storing to unverified. Poll the customer endpoint every 2-3 seconds until the state is unverified before creating the identity verification.

GET /api/customers/{customer_guid}
Authorization: Bearer YOUR_TOKEN

{
  "created_at": "2026-01-21T21:37:23.172157Z",
  "updated_at": "2026-01-21T21:37:24.240265Z",
  "guid": "customer_guid",
  "bank_guid": "bank_guid",
  "type": "business",
  "state": "unverified",
  "labels": null,
  "compliance_decisions": [],
  "activity_limits": []
}

ℹ️
State transitions
Business customers automatically transition from storing to unverified within a few seconds. If the state doesn't update, verify you created the customer successfully.

Create identity verification

Create an identity verification with type: kyc and method: business_registration.

POST /api/identity_verifications
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "type": "kyc",
  "method": "business_registration",
  "customer_guid": "customer_guid"
}

{
  "created_at": "2026-01-21T21:43:17.994448Z",
  "updated_at": "2026-01-21T21:43:17.994448Z",
  "type": "kyc",
  "guid": "identity_verification_guid",
  "method": "business_registration",
  "customer_guid": "customer_guid",
  "state": "storing",
  "outcome": null,
  "failure_codes": [],
  "country_code": "US",
  "compliance_decisions": []
}

ℹ️
Business verification type
The API uses type: kyc for both individual and business verifications. Set method: business_registration to perform KYB instead of KYC.

ℹ️
Sandbox testing options
The expected_behaviours field is available in the sandbox to specify how you want the verification to be returned. This is helpful for testing success/failure scenarios. Remove the expected_behaviours key completely for normal operation, or include passed_immediately or failed_immediately for testing purposes.

Retrieve the Persona Inquiry ID

Poll the identity verification endpoint to retrieve the persona_inquiry_id. You need this ID to launch the Persona verification flow.

GET /api/identity_verifications/{identity_verification_guid}
Authorization: Bearer YOUR_TOKEN

{
  "created_at": "2026-01-21T21:43:17.994448Z",
  "updated_at": "2026-01-21T21:43:18.811961Z",
  "type": "kyc",
  "guid": "identity_verification_guid",
  "method": "business_registration",
  "customer_guid": "customer_guid",
  "state": "waiting",
  "outcome": null,
  "failure_codes": [],
  "country_code": "US",
  "persona_inquiry_id": "inq_XXXXXXXXXXXXX",
  "persona_state": "waiting",
  "compliance_checks": [],
  "compliance_decisions": [],
  "business_associates": []
}

Launch Persona verification

Launch Persona SDK or redirect to the Persona web flow using the persona_inquiry_id.

Use Persona SDK

ℹ️
SDK installation
For NPM and CDN installation instructions, see Verifying a Customer.

import Persona from 'persona';

const client = new Persona.Client({
  inquiryId: 'persona_inquiry_id',
  language: 'en',
  onReady: () => client.open(),
  onComplete: ({ inquiryId, status, fields }) => {
    console.log(`Sending finished inquiry ${inquiryId} to backend`);
    // Poll Cybrid API to confirm verification completion
    // Or use Webhooks to be updated on identity_verification.completed
  },
  onCancel: ({ inquiryId, sessionToken }) => {
    console.log('User cancelled verification');
  },
  onError: (error) => {
    console.error('Verification error:', error);
  }
});

Use the hosted flow

Add the inquiry ID to the Persona verification URL and redirect your customer. Replace inq_XXXXXXXXXXXXX with the inquiry ID from previous step:

https://withpersona.com/verify?inquiry-id=inq_XXXXXXXXXXXXX

Handle Persona events

The Persona SDK provides event callbacks to track the verification flow. For detailed event handling, see Persona's event handling documentation.

Key callbacks:

onReady: Called when the SDK is ready to display
onComplete: Called when the user completes verification flow (the identity verification could still fail)
onCancel: Called when the user cancels the flow
onError: Called when an error occurs

Language support:

The language parameter accepts ISO 639-1 language codes. See Persona's supported languages for the full list.

⚠️
Logging for troubleshooting
Implement logging in each callback handler. This helps troubleshoot verification issues and track user progress through the identity verification flow.

Verify Ultimate Beneficial Owners

During the KYB flow, your customers provide information about Ultimate Beneficial Owners (UBOs). Each UBO must complete a separate KYC verification.

Persona sends UBOs an email with their verification link. UBOs may overlook these emails or their email providers may filter them to spam.

Poll the identity verification endpoint to detect when the business verification moves to pending state. Alternatively, subscribe to the identity_verification.pending webhook event.

Retrieve the business_associates array and proactively initiate KYC for each UBO.

GET /api/identity_verifications/{identity_verification_guid}
Authorization: Bearer YOUR_TOKEN

{
  "created_at": "2026-01-21T21:43:17.994448Z",
  "updated_at": "2026-01-27T17:42:52.506307Z",
  "type": "kyc",
  "guid": "identity_verification_guid",
  "method": "business_registration",
  "customer_guid": "customer_guid",
  "state": "pending",
  "outcome": null,
  "failure_codes": [],
  "country_code": "US",
  "persona_inquiry_id": "inq_XXXXXXXXXXXXX",
  "persona_state": "processing",
  "compliance_checks": [
    {
      "type": "business_verification",
      "outcome": "passed",
      "failure_codes": []
    },
    {
      "type": "business_tax_id_verification",
      "outcome": "passed",
      "failure_codes": []
    },
    {
      "type": "business_watchlists",
      "outcome": "passed",
      "failure_codes": []
    }
  ],
  "compliance_decisions": [],
  "business_associates": [
    {
      "role": "director",
      "persona_inquiry_id": "inq_XXXXXXXXXXXXX",
      "email_address": "[email protected]",
      "persona_state": "waiting",
      "state": "waiting"
    },
    {
      "role": "owner",
      "persona_inquiry_id": "inq_XXXXXXXXXXXXX",
      "email_address": "[email protected]",
      "persona_state": "waiting",
      "state": "waiting"
    }
  ]
}

⚠️
UBO verification is required
The KYB process cannot complete until all business associates complete their individual KYC verifications. Monitor the business_associates array to track progress.

Extract the persona_inquiry_id from each object in the business_associates array. Use Persona SDK or web redirect (as shown above) to guide each UBO through their KYC verification.

Verify completion status

When the user completes the Persona flow, poll the Cybrid API to confirm verification success.

Check identity verification status

Poll GET /api/identity_verifications/{identity_verification_guid} until state: completed and outcome: passed. This confirms both the business entity and all UBOs completed verification successfully.

GET /api/identity_verifications/{identity_verification_guid}
Authorization: Bearer YOUR_TOKEN

{
  "created_at": "2026-01-21T21:43:17.994448Z",
  "updated_at": "2026-01-27T18:15:32.847219Z",
  "type": "kyc",
  "guid": "identity_verification_guid",
  "method": "business_registration",
  "customer_guid": "customer_guid",
  "state": "completed",
  "outcome": "passed",
  "failure_codes": [],
  "country_code": "US",
  "persona_inquiry_id": "inq_XXXXXXXXXXXXX",
  "persona_state": "completed",
  "compliance_checks": [
    {
      "type": "business_verification",
      "outcome": "passed",
      "failure_codes": []
    },
    {
      "type": "business_tax_id_verification",
      "outcome": "passed",
      "failure_codes": []
    },
    {
      "type": "business_watchlists",
      "outcome": "passed",
      "failure_codes": []
    }
  ],
  "compliance_decisions": [],
  "business_associates": [
    {
      "role": "director",
      "persona_inquiry_id": "inq_XXXXXXXXXXXXX",
      "email_address": "[email protected]",
      "persona_state": "completed",
      "state": "completed"
    },
    {
      "role": "owner",
      "persona_inquiry_id": "inq_XXXXXXXXXXXXX",
      "email_address": "[email protected]",
      "persona_state": "completed",
      "state": "completed"
    }
  ]
}

ℹ️
Verification failures
If outcome: failed, check the failure_codes array for specific issues. Common failure reasons include incomplete documentation, watchlist matches, or inconsistent information.

Confirm customer verification

After the identity verification completes and passes, confirm the customer entered the verified state. Call GET /api/customers/{customer_guid} and verify state: verified:

{
  "created_at": "2026-01-21T21:37:23.172157Z",
  "updated_at": "2026-01-27T18:15:33.128445Z",
  "guid": "customer_guid",
  "bank_guid": "bank_guid",
  "type": "business",
  "state": "verified",
  "labels": null,
  "compliance_decisions": [],
  "activity_limits": []
}

Next steps

Once your business customer is verified, you can proceed with:

Generate quote for trading
Funding accounts via bank transfer
Execute trades to buy or sell crypto

For more information on identity verification workflows, see Verifying a customer.