Headless KYC for users with Bridge

With headless KYC, your app’s server submits a user’s verification data to Privy, and Privy forwards it to Bridge. No hosted Bridge link is involved, so your app owns the interface end to end and controls how each field is collected. Use hosted KYC instead when Bridge should collect the data, including document capture and liveness checks. At a high level, headless KYC involves three steps:

Accept terms of service

The user accepts Bridge’s terms of service, which produces an agreement ID.

Submit verification data

Your app’s server submits the user’s identity data, along with that agreement ID.

Track status

Bridge reviews the submission asynchronously. Your app polls status or consumes webhooks.

Before verifying users, register a Bridge API key with Privy and enable server-side flows for the environment the requests target.

Accept terms of service

Bridge requires a signed terms of service agreement before it will create or update a customer. Generate an acceptance link with POST /v1/users/{user_id}/kyc/tos, pass it to your frontend, and keep the agreement ID Bridge returns when the user accepts. Pass that ID as client_agreement_id on the submission. Privy stores it, so later submissions for the same user may omit it and Privy replays the stored one.

Submit verification data

Use the submit 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 status = await privy.users().kyc.submit('did:privy:xxxxx', {
  provider: 'bridge',
  environment: 'sandbox',
  endorsements: ['base'],
  client_agreement_id: '<agreement-id-from-tos-acceptance>',
  data: {
    first_name: 'Alex',
    last_name: 'Doe',
    email: '[email protected]',
    date_of_birth: '1990-01-31',
    residential_address: {
      street_line_1: '123 Market Street',
      city: 'San Francisco',
      subdivision: 'CA',
      postal_code: '94103',
      country: 'USA'
    },
    identifying_information: [
      {
        type: 'ssn',
        issuing_country: 'USA',
        number: '000-00-0000'
      }
    ]
  }
});

// status.kyc.status is Bridge's verification status
// status.requirements_due lists what Bridge is still waiting on

The first submission must carry enough data for Bridge to begin verification: name, date of birth, residential address, and at least one identifying document.

Later submissions update the same Bridge customer. Omitted top-level fields are left untouched, including email; sending a different email replaces the address Bridge has on file, and since Bridge identifies customers by email, the old address stops resolving to this one. Nested objects such as a residential_address are replaced whole. If a response never reached you, resubmit the identical data.

Bridge allows one customer per email address, across individuals and businesses alike. A submission whose email already has a Bridge customer returns 409 — Privy will not adopt an existing customer, since an email in a request body is not proof the user owns it. Submit a different email, or contact [email protected] to link an existing Bridge customer to a Privy user.

Nonresident alien attestation

data.nonresident_alien_attestation attests that the user is a nonresident alien, which can satisfy identification without a US tax ID. It is one input to Bridge’s nonresident alien eligibility, not all of it, and Bridge must enable the capability for your account before it is accepted. It applies to individuals only and is rejected on business customers, so it is not part of a KYB submission.

KYC and KYB

Users

Organizations

Headless KYC

Accept terms of service

Submit verification data

Nonresident alien attestation

Next steps

Track KYC status

Headless KYB

​Accept terms of service

​Submit verification data

​Nonresident alien attestation

​Next steps

Track KYC status

Headless KYB

Accept terms of service

Submit verification data

Nonresident alien attestation

Next steps