Track KYC status

Poll a user’s KYC status or subscribe to verification webhooks

Verification is asynchronous. Bridge reviews the submission after the user completes the hosted flow, and can revoke an endorsement later. Your app can poll for status or subscribe to webhooks. See Bridge’s customer status lifecycle for how Bridge derives each status.

Before tracking status, create a KYC link for the user.

Fetch by API

Use the list method from the kyc resource on users().

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

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

const {kyc_statuses: statuses} = await privy.users().kyc.list('did:privy:xxxxx');

// one entry per provider the user has been verified with
for (const status of statuses) {
  console.log(status.provider, status.kyc.status, status.endorsements);
}

Webhooks

Privy emits a user.kyc.updated webhook whenever a user’s verification state changes at Bridge, re-emitting Bridge’s customer webhooks as a Privy event. The payload carries a full state snapshot in data and a changes diff of the fields that moved, so your app can react to a specific transition without storing prior state.

Webhooks can be tested at no cost in development environments. To enable webhooks in production, upgrade to the Enterprise plan in the Privy Dashboard.

Hide user.kyc.updated attributes

type · 'user.kyc.updated' · required

Type of the webhook event.

user_id · string · required

ID of the Privy user whose verification state changed.

provider · 'bridge' · required

Provider that reported the change.

environment · 'production' | 'sandbox' · required

Bridge environment the customer belongs to.

data · object · required

Full snapshot of the user’s verification state at the time of the event.

Hide properties

data.status · string · required

Top-level status of the customer, as reported by Bridge.

data.tos · object · required

Terms of service state, containing status.

data.kyc · object · required

Verification state, containing status.

data.endorsements · object[] · required

Endorsements for the user. Each entry contains name, status, and missing, which is null when the endorsement is complete.

data.capabilities · object · required

Status of payin_crypto, payout_crypto, payin_fiat, and payout_fiat.

changes · object · required

Fields that changed, keyed by dot-notation path. Each value is a [previous, current] tuple. Privy omits events where no meaningful verification field changed.

Example: base endorsement approved

{
  "type": "user.kyc.updated",
  "user_id": "did:privy:xxxxx",
  "provider": "bridge",
  "environment": "sandbox",
  "data": {
    "status": "active",
    "tos": {
      "status": "approved"
    },
    "kyc": {
      "status": "active"
    },
    "endorsements": [
      {
        "name": "base",
        "status": "approved",
        "missing": null
      }
    ],
    "capabilities": {
      "payin_crypto": "active",
      "payout_crypto": "active",
      "payin_fiat": "pending",
      "payout_fiat": "pending"
    }
  },
  "changes": {
    "endorsements.base.status": ["incomplete", "approved"],
    "capabilities.payin_crypto": ["pending", "active"]
  }
}

If an endorsement is incomplete, read data.endorsements[].missing for the requirements Bridge is still waiting on, then create a new KYC link for the user to resolve them.

Next steps

Handling webhook events

Configure an endpoint to receive Privy webhook events

KYB

Verify an organization