> ## 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.

# Hosted link

> Verify an organization through a Bridge-hosted KYB flow

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.

Before creating a KYB link, see [hosted terms of service](/kyc-kyb/kyb-tos) or, if Bridge has approved your app, [terms of service reliance](/kyc-kyb/kyb-tos-reliance) for how to collect an authorized representative's acceptance. The representative then submits the organization's information through a hosted verification flow. To collect that data in your own interface instead, see [headless KYB](/kyc-kyb/kyb-headless).

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>

## Create a KYB link

<View title="NodeJS" icon="node-js">
  Use the `initiateLinks` method from the `kyb` resource on `organizations()`.

  ```ts {skip-check} theme={"system"}
  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: 'finance@example.com',
    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
  ```
</View>

<View title="Python" icon="python">
  Use `initiate_links` to create a hosted KYB link.

  ```python theme={"system"}
  status = client.organizations.kyb.initiate_links(
      "organization-id",
      provider="bridge",
      environment="sandbox",
      email="finance@example.com",
      business_name="Acme, Inc.",
      endorsements=["base"],
      redirect_uri="https://your-app.com/kyb/complete",
  )

  # Pass status.kyb.link to your frontend.
  ```
</View>

<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
  ```

  See the [API reference](/api-reference/fiat/kyb/links) for the full request and response schema.

  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 resolving to your app's stored record of the organization's terms of service
    acceptance. Only applicable if Bridge has approved the app for [terms of service
    reliance](/kyc-kyb/kyb-tos-reliance).
  </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@example.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="Headless KYB" icon="code" href="/kyc-kyb/kyb-headless">
    Submit an organization's verification data from your server
  </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>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.