KYC for users with Bridge

Privy verifies an individual user with Bridge. Privy creates the Bridge customer on the first request and links it to the Privy user, so your app only ever references the Privy user ID. At a high level, KYC involves two steps:

Accept terms of service

The user accepts Bridge’s terms of service through a hosted link.

Perform identity verification

The user submits their identity information through a hosted verification flow.

Bridge currently supports hosted KYC only. Both endpoints return a link that your app passes to its frontend for the user to open and complete.

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

Accept terms of service

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

https://api.privy.io/v1/users/{user_id}/kyc/tos

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

'bridge'

required

Provider to verify the user with.

'production' | 'sandbox'

Bridge environment to use. Defaults to production.

string

Email address for the Bridge customer. Falls back to the user’s linked email account. Required if the user has no linked email.

Below is a sample cURL command for this request:

curl --request POST https://api.privy.io/v1/users/did:privy:xxxxx/kyc/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]"
  }'

A successful response includes the following fields:

'bridge'

Provider the user 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 user 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 user can accept the terms of service. The request is idempotent: calling it again for the same user returns a link for the existing Bridge customer.

Create a KYC link

To generate a hosted KYC link for a user, make a POST request to:

https://api.privy.io/v1/users/{user_id}/kyc/links

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

'bridge'

required

Provider to verify the user with.

'production' | 'sandbox'

Bridge environment to use. Defaults to production.

string

Email address for the Bridge customer. Falls back to the user’s linked email account. Required if the user has no linked email.

string[]

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

string

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

string

Identifier of the terms of service agreement the user 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/users/did:privy:xxxxx/kyc/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]",
    "endorsements": ["base"],
    "redirect_uri": "https://your-app.com/kyc/complete"
  }'

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

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

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

Track KYC status

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

Next steps

Track KYC status

Poll a user’s verification status or subscribe to webhooks

KYB

Verify an organization

Handling webhook events

Configure an endpoint to receive Privy webhook events

KYC and KYB

Users

Organizations

KYC

Accept terms of service

Create a KYC link

Track KYC status

Next steps

Track KYC status

KYB

Handling webhook events

​Accept terms of service

​Create a KYC link

​Track KYC status

​Next steps

Track KYC status

KYB

Handling webhook events

Accept terms of service

Create a KYC link

Track KYC status

Next steps