@vuplicitychecks/sdk

Official Node SDK for Vuplicity's developer-first screening platform.

Use it to:

• create hosted screening sessions
• fetch hosted session status
• verify outbound webhook signatures
• exercise deterministic sandbox scenarios safely

Install

npm install @vuplicitychecks/sdk

Quickstart

import { Vuplicity } from '@vuplicitychecks/sdk';

const vuplicity = new Vuplicity(process.env.VUPLICITY_API_KEY!);

const session = await vuplicity.screening.createSession({
  candidate: {
    first_name: 'Jane',
    last_name: 'Doe',
    email: '[email protected]',
    position: 'Operations Manager',
  },
  package: 'essential',
  redirect_url: 'https://app.example.com/screening/complete',
  webhook_url: 'https://app.example.com/api/vuplicity/webhooks',
  include_monitoring: true,
  branding: {
    company_name: 'Example Inc.',
    support_email: '[email protected]',
  },
});

console.log(session.session_url);

Redirect your candidate to session.session_url. Vuplicity handles disclosure, authorization, intake, submission, need-info loops, and completion handoff.

Sandbox

Use sandbox headers without touching live providers:

await vuplicity.screening.createSession(payload, {
  mode: 'sandbox',
  scenario: 'need_info',
});

Supported scenarios:

• clear
• record_found
• need_info
• dispute
• monitoring_hit

Fetch Session Status

const sessionView = await vuplicity.screening.getSession(session.session_id);

console.log(sessionView.state);

Verify Webhooks

import { verifyVuplicityWebhookSignature } from '@vuplicitychecks/sdk';

const verification = verifyVuplicityWebhookSignature({
  payload: rawBody,
  secret: process.env.VUPLICITY_WEBHOOK_SECRET!,
  headers: req.headers,
});

if (!verification.valid) {
  throw new Error(`Invalid Vuplicity webhook: ${verification.reason}`);
}

The verifier supports:

• legacy x-vuplicity-signature
• timestamped x-vuplicity-signature-v2

Docs

• Quickstart: developers.vuplicity.com
• Webhook lifecycle, monitoring, and sandbox guidance are also documented on the same developer portal.