KYB

Verify an organization with terms of service acceptance and a hosted KYB flow

Privy verifies an organization with Bridge. Privy creates the Bridge business customer on the first request and links it to the Privy organization, so your app only ever references the Privy organization ID.

At a high level, KYB involves two steps:

1. Accept terms of service

   An authorized representative of the organization accepts Bridge’s terms of service through a hosted link.

2. Perform business verification

   The representative submits the organization’s information through a hosted verification flow.

Bridge currently supports hosted KYB only. Both endpoints return a link that your app passes to its frontend for an authorized representative of the organization to open and complete.

Before verifying organizations, register a Bridge API key with Privy.

Bridge reviews business customers manually, so KYB usually takes longer than KYC for an individual. Bridge may also require the organization’s associated persons to complete their own verification.

Accept terms of service

Use the initiateTos method from the kyb resource on organizations().

import {PrivyClient} from '@privy-io/node';

const privy = new PrivyClient({
  appId: process.env.PRIVY_APP_ID!,
  appSecret: process.env.PRIVY_APP_SECRET!
});

const tos = await privy.organizations().kyb.initiateTos('<organization-id>', {
  provider: 'bridge',
  environment: 'sandbox',
  email: '[e-mail]',
  business_name: 'Acme, Inc.'
});

// tos.link is the terms of service link to pass to your frontend

Pass the link to your app’s frontend so the organization’s representative can accept the terms of service. The request is idempotent: calling it again for the same organization returns a link for the existing Bridge customer.

Create a KYB link

Use the initiateLinks method from the kyb resource on organizations().

import {PrivyClient} from '@privy-io/node';

const privy = new PrivyClient({
  appId: process.env.PRIVY_APP_ID!,
  appSecret: process.env.PRIVY_APP_SECRET!
});

const status = await privy.organizations().kyb.initiateLinks('<organization-id>', {
  provider: 'bridge',
  environment: 'sandbox',
  email: '[e-mail]',
  business_name: 'Acme, Inc.',
  endorsements: ['base'],
  redirect_uri: 'https://your-app.com/kyb/complete'
});

// status.kyb.link is the hosted KYB link to pass to your frontend

Pass kyb.link to your app’s frontend so the organization’s representative can complete verification. The request is idempotent: calling it again for the same organization returns the existing link.

Track KYB status

Verification is asynchronous. Bridge reviews the submission after the representative completes the hosted flow, and can revoke an endorsement later. See track KYB status to poll an organization’s status or subscribe to webhooks.

Next steps

Track KYB status

Poll an organization’s verification status or subscribe to webhooks

Organization wallets

Create wallets an organization’s members can operate together

Handling webhook events

Configure an endpoint to receive Privy webhook events