SDK quickstart

The Web SDK gets a verification session on screen without you building any capture UI yourself. Install @personablocks/kyc-sdk from npm, or load the hosted sdk/v1.js script directly, then call PersonaBlocks.create() with a session token to open the flow.

The SDK picks the right venue automatically — an embedded iframe for phone-rail customers, a popup for wallet-based sign-in, or a plain redirect as a fallback — so the same integration works across devices without extra branching in your code.

The mental model

Note

All capture UI — camera, wallet signature, document upload — always loads from PersonaBlocks-controlled origins inside an iframe or popup. Nothing sensitive ever ships inside your bundle. This is the same split as @stripe/stripe-js: the package you install is a thin, versioned loader for a hosted script, not the flow itself.

The minimum viable integration is three steps:

1. Mint a session server-side with your secret key (POST /v1/verification-sessions) and hand the returned client_token (pbvs_...) to your frontend.
2. Call PersonaBlocks.create({ clientToken }) to build an instance.
3. Call .open() on that instance to launch the flow.

Install

Both integration paths are first-class — pick whichever fits your build. The script tag needs no bundler; the npm package gives you types and tree-shaking. Either way, capture runs on PersonaBlocks origins, not in your bundle.

Script tag

Drop the hosted loader onto your page as a classic script, then call PersonaBlocks.create():

<script src="https://app.personablocks.io/sdk/v1.js"></script>
<script>
  const pb = PersonaBlocks.create({
    clientToken: 'pbvs_...', // minted server-side via POST /v1/verification-sessions
    flow: 'auto', // 'auto' | 'wallet' | 'phone'
    onComplete: ({ sessionId, vicId, method }) => {
      // IDs only — verdict/tier data is a server-to-server (webhook) concern.
    },
    onError: ({ type, recoverable, message }) => {},
  });
  pb.open();
</script>

The loader must be a classic <script> — never type="module". It captures document.currentScript the instant it runs to learn which origin to load the flow from, and document.currentScript is always null for module scripts.

sdk/v1.js is evergreen — it always serves the latest v1 build. To pin an exact build, load https://app.personablocks.io/sdk/v<current release version>.js instead (e.g. v1.2.0.js) — the served build’s version stamp always matches PersonaBlocks.version. Read the loaded version at runtime from PersonaBlocks.version.

npm

npm install @personablocks/kyc-sdk

loadPersonaBlocks() injects the same hosted script and resolves once window.PersonaBlocks is ready. Pass scriptOrigin explicitly — it defaults to your own page’s origin, which is rarely a PersonaBlocks host:

import { loadPersonaBlocks } from '@personablocks/kyc-sdk';

const pb = await loadPersonaBlocks({
  // Optional: the origin to load /sdk/v1.js from. Defaults to
  // window.location.origin — pass this explicitly for the common case where
  // your page is not itself served from a PersonaBlocks-fronted domain.
  scriptOrigin: 'https://app.personablocks.io',
});

const instance = pb.create({
  clientToken: 'pbvs_...',
  flow: 'auto',
  container: '#pb-mount', // ignored by the popup/wallet venue
  onReady: () => instance.open(),
  onComplete: ({ sessionId, vicId, method }) => {},
  onCancel: ({ resumeToken }) => {},
  onError: ({ type, recoverable, message }) => {},
});

loadPersonaBlocks() is idempotent — call it from as many components as you like; the hosted script is injected only once per page, and every caller resolves against the same window.PersonaBlocks.

What to read next

• SDK reference — every create() option, callback, and error type.
• React — the usePersonaBlocks hook and <PersonaBlocksVerify> component.
• Theming — match the flow to your brand with appearance.
• Venues — how the iframe, popup, and redirect flows behave.