> ## Documentation Index
> Fetch the complete documentation index at: https://docs.privy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# KYB

Privy verifies an [organization](/organizations/overview) with Bridge. Privy creates the [Bridge business customer](https://apidocs.bridge.xyz/platform/customers/customers/api) 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:

<Steps>
  <Step title="Accept terms of service">
    An authorized representative of the organization accepts Bridge's terms of service through a
    hosted link.
  </Step>

  <Step title="Perform business verification">
    The representative submits the organization's information through a hosted verification flow.
  </Step>
</Steps>

<Info>
  Bridge currently supports [hosted
  KYB](https://apidocs.bridge.xyz/platform/customers/customers/kyclinks) only. Both endpoints return
  a link that your app passes to its frontend for an authorized representative of the organization
  to open and complete.
</Info>

Before verifying organizations, [register a Bridge API key with Privy](/kyc-kyb/setup).

<Tip>
  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.
</Tip>

## Accept terms of service

<View title="REST API" icon="terminal">
  To generate a [terms of service](https://apidocs.bridge.xyz/platform/customers/customers/tos) link
  for an organization, make a `POST` request to:

  ```bash theme={"system"}
  https://api.privy.io/v1/organizations/{organization_id}/kyb/tos
  ```

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

  <ParamField body="provider" type="'bridge'" required>
    Provider to verify the organization with.
  </ParamField>

  <ParamField body="environment" type="'production' | 'sandbox'">
    Bridge environment to use. Defaults to `production`.
  </ParamField>

  <ParamField body="email" type="string" required>
    Email address for the Bridge business customer. Bridge sends requests for information to this
    address.
  </ParamField>

  <ParamField body="business_name" type="string">
    Legal name of the business.
  </ParamField>

  Below is a sample cURL command for this request:

  ```bash theme={"system"}
  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": "finance@acme.com",
      "business_name": "Acme, Inc."
    }'
  ```

  A successful response includes the following fields:

  <ResponseField name="provider" type="'bridge'">
    Provider the organization is being verified with.
  </ResponseField>

  <ResponseField name="environment" type="'production' | 'sandbox'">
    Bridge environment used for the request.
  </ResponseField>

  <ResponseField name="status" type="string">
    Status of terms of service acceptance, as reported by Bridge.
  </ResponseField>

  <ResponseField name="link" type="string">
    URL the organization's representative opens to accept Bridge's terms of service.
  </ResponseField>

  ```json theme={"system"}
  {
    "provider": "bridge",
    "environment": "sandbox",
    "status": "pending",
    "link": "https://compliance.sandbox.bridge.xyz/accept-tos?customer_id=..."
  }
  ```
</View>

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

<View title="REST API" icon="terminal">
  To generate a hosted KYB link for an organization, make a `POST` request to:

  ```bash theme={"system"}
  https://api.privy.io/v1/organizations/{organization_id}/kyb/links
  ```

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

  <ParamField body="provider" type="'bridge'" required>
    Provider to verify the organization with.
  </ParamField>

  <ParamField body="environment" type="'production' | 'sandbox'">
    Bridge environment to use. Defaults to `production`.
  </ParamField>

  <ParamField body="email" type="string" required>
    Email address for the Bridge business customer.
  </ParamField>

  <ParamField body="business_name" type="string">
    Legal name of the business.
  </ParamField>

  <ParamField body="endorsements" type="string[]">
    [Endorsements](https://apidocs.bridge.xyz/platform/customers/customers/endorsements) to request
    from Bridge. Each endorsement unlocks a set of rails and regions. Defaults to `['base']`.
  </ParamField>

  <ParamField body="redirect_uri" type="string">
    URI the representative is redirected to after completing the hosted flow.
  </ParamField>

  <ParamField body="client_agreement_id" type="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](https://apidocs.bridge.xyz/platform/customers/compliance/terms-of-service-reliance) with
    Bridge.
  </ParamField>

  Below is a sample cURL command for this request:

  ```bash theme={"system"}
  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": "finance@acme.com",
      "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](#track-kyb-status) for the complete set of fields.

  ```json theme={"system"}
  {
    "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": []
  }
  ```
</View>

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](/kyc-kyb/kyb-status) to poll an organization's status or subscribe to webhooks.

## Next steps

<CardGroup cols={2}>
  <Card title="Track KYB status" icon="magnifying-glass" href="/kyc-kyb/kyb-status">
    Poll an organization's verification status or subscribe to webhooks
  </Card>

  <Card title="Organization wallets" icon="building" href="/organizations/overview">
    Create wallets an organization's members can operate together
  </Card>

  <Card title="Handling webhook events" icon="webhook" href="/user-management/users/webhooks/handling-events">
    Configure an endpoint to receive Privy webhook events
  </Card>
</CardGroup>