Track KYC status with Bridge

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

To read a user’s current KYC status, make a GET request to:

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

The endpoint accepts the following query parameter:

'bridge'

Only return status for this provider. If omitted, the response includes every provider the user has been verified with.

Below is a sample cURL command for this request:

curl --request GET 'https://api.privy.io/v1/users/did:privy:xxxxx/kyc?provider=bridge' \
  -u "<your-privy-app-id>:<your-privy-app-secret>" \
  -H "privy-app-id: <your-privy-app-id>"

The response is an array with one entry per provider. Privy fetches status from Bridge on every request, so revoked endorsements are reflected immediately.

'bridge'

Provider that verified the user.

'production' | 'sandbox'

Bridge environment the customer belongs to.

string

Top-level status of the customer, as reported by Bridge. A customer is active once any endorsement is approved.

object

Hide properties

string

Status of terms of service acceptance.

string

URL to accept the terms of service. Present while acceptance is pending.

object

Verification state.

Hide properties

string

Status of the user’s verification.

string

URL to complete verification. Present while verification is outstanding.

string[]

Reasons Bridge rejected the submission.

object[]

Endorsements requested for the user.

Hide properties

string

Name of the endorsement, such as base or sepa.

string

Status of the endorsement, as reported by Bridge.

string[] | null

Requirements Bridge is still waiting on. null when the endorsement is complete.

object

Status of each capability the customer can use.

Hide properties

string

Whether the customer can deposit crypto.

string

Whether the customer can receive crypto payouts.

string

Whether the customer can deposit fiat.

string

Whether the customer can receive fiat payouts.

string[]

Requirements the user must still satisfy, such as linking a bank account.

string[]

Requirements the user will need to satisfy in the future.

[
  {
    "provider": "bridge",
    "environment": "sandbox",
    "status": "active",
    "tos": {
      "status": "approved"
    },
    "kyc": {
      "status": "approved",
      "rejection_reasons": []
    },
    "endorsements": [
      {
        "name": "base",
        "status": "approved",
        "missing": null
      }
    ],
    "capabilities": {
      "payin_crypto": "active",
      "payout_crypto": "active",
      "payin_fiat": "active",
      "payout_fiat": "active"
    },
    "requirements_due": [],
    "future_requirements_due": []
  }
]

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

'user.kyc.updated'

required

Type of the webhook event.

string

required

ID of the Privy user whose verification state changed.

'bridge'

required

Provider that reported the change.

'production' | 'sandbox'

required

Bridge environment the customer belongs to.

object

required

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

Hide properties

string

required

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

object

required

object

required

Verification state, containing status.

object[]

required

Endorsements for the user. 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": "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.

KYC and KYB

Users

Organizations

Track KYC status

Fetch by API

Webhooks

Next steps

Handling webhook events

KYB

​Fetch by API

​Webhooks

​Next steps

Handling webhook events

KYB

Fetch by API

Webhooks

Next steps