KYB for organizations with Bridge

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:

Accept terms of service

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

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

To generate a terms of service link for an organization, make a POST request to:

https://api.privy.io/v1/organizations/{organization_id}/kyb/tos

In the body of the request, include the following fields:

'bridge'

required

Provider to verify the organization with.

'production' | 'sandbox'

Bridge environment to use. Defaults to production.

string

required

Email address for the Bridge business customer. Bridge sends requests for information to this address.

string

Legal name of the business.

Below is a sample cURL command for this request:

curl --request POST https://api.privy.io/v1/organizations/xxxxx/kyb/tos \
  -u "<your-privy-app-id>:<your-privy-app-secret>" \
  -H "privy-app-id: <your-privy-app-id>" \
  -H 'Content-Type: application/json' \
  -d '{
    "provider": "bridge",
    "environment": "sandbox",
    "email": "[email protected]",
    "business_name": "Acme, Inc."
  }'

A successful response includes the following fields:

'bridge'

Provider the organization is being verified with.

'production' | 'sandbox'

Bridge environment used for the request.

string

Status of terms of service acceptance, as reported by Bridge.

string

URL the organization’s representative opens to accept Bridge’s terms of service.

{
  "provider": "bridge",
  "environment": "sandbox",
  "status": "pending",
  "link": "https://compliance.sandbox.bridge.xyz/accept-tos?customer_id=..."
}

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

To generate a hosted KYB link for an organization, make a POST request to:

https://api.privy.io/v1/organizations/{organization_id}/kyb/links

In the body of the request, include the following fields:

'bridge'

required

Provider to verify the organization with.

'production' | 'sandbox'

Bridge environment to use. Defaults to production.

string

required

Email address for the Bridge business customer.

string

Legal name of the business.

string[]

Endorsements to request from Bridge. Each endorsement unlocks a set of rails and regions. Defaults to ['base'].

string

URI the representative is redirected to after completing the hosted flow.

string

Identifier of the terms of service agreement the organization accepted in your app. Only applicable if your app has arranged terms of service reliance with Bridge.

Below is a sample cURL command for this request:

curl --request POST https://api.privy.io/v1/organizations/xxxxx/kyb/links \
  -u "<your-privy-app-id>:<your-privy-app-secret>" \
  -H "privy-app-id: <your-privy-app-id>" \
  -H 'Content-Type: application/json' \
  -d '{
    "provider": "bridge",
    "environment": "sandbox",
    "email": "[email protected]",
    "business_name": "Acme, Inc.",
    "endorsements": ["base"],
    "redirect_uri": "https://your-app.com/kyb/complete"
  }'

The response is the organization’s full KYB status, including the link to complete verification. See Track KYB status for the complete set of fields.

{
  "provider": "bridge",
  "environment": "sandbox",
  "status": "not_started",
  "tos": {
    "status": "approved"
  },
  "kyb": {
    "status": "not_started",
    "link": "https://bridge.withpersona.com/verify?..."
  },
  "endorsements": [
    {
      "name": "base",
      "status": "incomplete",
      "missing": ["proof_of_ownership"]
    }
  ],
  "capabilities": {
    "payin_crypto": "pending",
    "payout_crypto": "pending",
    "payin_fiat": "pending",
    "payout_fiat": "pending"
  },
  "requirements_due": [],
  "future_requirements_due": []
}

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

KYC and KYB

Users

Organizations

KYB

Accept terms of service

Create a KYB link

Track KYB status

Next steps

Track KYB status

Organization wallets

Handling webhook events

​Accept terms of service

​Create a KYB link

​Track KYB status

​Next steps

Track KYB status

Organization wallets

Handling webhook events

Accept terms of service

Create a KYB link

Track KYB status

Next steps