Track KYB status with Bridge

Verification is asynchronous. Bridge reviews the submission after the representative 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 KYB link for the organization.

Fetch by API

Use the list method from the kyb resource on organizations().

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

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

const {kyb_statuses: statuses} = await privy.organizations().kyb.list('<organization-id>');

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

Acting on requirements

Each entry in requirements_due and endorsements[].missing names data Bridge is still waiting on. How you satisfy it depends on the flow:

Headless: collect the data and call POST /v1/organizations/{organization_id}/kyb/submit again with just the new fields. Submissions are re-entrant, so this updates the existing Bridge customer.
Hosted: create a new hosted KYB link and send the organization back through it.

Both flows act on the same Bridge customer, so a requirement the headless fields cannot express can always be completed through a hosted link. An empty requirements_due alongside an approved endorsement means nothing is outstanding.

Webhooks

Privy emits an organization.kyb.updated webhook whenever an organization’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 organization.kyb.updated attributes

'organization.kyb.updated'

required

Type of the webhook event.

string

required

ID of the Privy organization whose verification state changed.

'bridge'

required

Provider that reported the change.

'production' | 'sandbox'

required

Bridge environment the business customer belongs to.

object

required

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

Hide properties

string

required

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

object

required

object

required

Verification state, containing status.

object[]

required

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

object

required

Status of payin_crypto, payout_crypto, payin_fiat, and payout_fiat.

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": "organization.kyb.updated",
  "organization_id": "xxxxx",
  "provider": "bridge",
  "environment": "sandbox",
  "data": {
    "status": "active",
    "tos": {
      "status": "approved"
    },
    "kyb": {
      "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 KYB link for the organization to resolve them.

KYC and KYB

Users

Organizations

Track KYB status

Fetch by API

Acting on requirements

Webhooks

Next steps

Handling webhook events

KYC

​Fetch by API

​Acting on requirements

​Webhooks

​Next steps

Handling webhook events

KYC

Fetch by API

Acting on requirements

Webhooks

Next steps