Turn screening into infrastructure.

Endpoint family

Hosted screening sessions

Server-created candidate flow for disclosure, consent, intake, document loops, and final submission.

Endpoint family

API keys

Authenticated organization bootstrap surface for connector-v1 machine access.

Endpoint family

Webhook subscriptions

Subscribe to outbound lifecycle events, inspect deliveries, and rotate signing secrets.

Endpoint family

Background checks

Organization-scoped check records, need-info files, cancellation, analysis, and conversation state.

Endpoint family

Verification platform

Quote packages, create verification orders, resolve exceptions, and manage specialized verification lanes.

Endpoint family

Monitoring

Enroll subjects, record hits, update enrollment status, and close billing cycles.

Endpoint family

Compliance Officer v2

Scope-gated, citation-first compliance guidance for approved paid organizations.

Endpoint family

Operational metrics

Organization and super-admin metrics for launch scorecards, health, workers, and webhook security.

Request shape

• Candidate identity and contact information
• Package code such as `basic`, `essential`, or `complete`
• Redirect URL for completion handoff
• Webhook URL for background-check, verification, and monitoring events

Session states

Package

Basic

Baseline criminal screening.

National criminal database, sex offender registry, global watchlist, and address history.

Good for lower-friction hiring lanes.

Package

Essential

Most common pre-hire package.

All Basic checks, plus county and state court searches upfront.

Good for routine hiring where local court coverage should already be in scope.

Package

Complete

Expanded screening for higher-risk roles.

All Essential checks, plus federal criminal search.

Good when broader criminal scope should be settled before release.

Capability

Employment verification

Checks past jobs.

EMPLOYMENT_VERIFICATION

Capability

Education verification

Checks school and degree claims.

EDUCATION_VERIFICATION

Capability

Reference verification

Collects references in the same order.

REFERENCE_VERIFICATION

Capability

Healthcare License Screening - Federal

Checks license status and federal exclusions.

HEALTHCARE_LICENSE_SCREENING_FEDERAL

Capability

Healthcare License Screening - State

Adds state sanctions and state-level review.

HEALTHCARE_LICENSE_SCREENING_STATE

Capability

Healthcare License Screening - Board

Adds board discipline and license actions.

HEALTHCARE_LICENSE_SCREENING_BOARD

Capability

DOT verification

Checks DOT records for driving roles.

DOT_VERIFICATION

Capability

Identity verification

Confirms the person is who they say they are.

ID_VERIFICATION

Capability

Address verification

Checks address history.

ADDRESS_VERIFICATION

Capability

Military verification

Checks military service claims.

MILITARY_VERIFICATION

Capability

Motor vehicle report

Checks driving records. State fee stays separate.

MVR

Capability

MVR + CDLIS

Checks commercial driving records. State and CDLIS fees stay separate.

MVR_CDLIS

Capability

Professional license verification

Checks professional license status when a role requires proof of credentialing.

LICENSE_VERIFICATION

Capability

MedEx

Medical exception and employer-configured follow-up lane when the selected package requires it.

MEDEX

Capability

Booking continuous monitoring

Healthcare-oriented continuous monitoring configuration managed by the employer, not the candidate.

BOOKING_CONTINUOUS_MONITORING

Capability

International criminal search

Country-specific international criminal screening through the provider jurisdiction matrix.

CRIMINAL_INTERNATIONAL

Capability

International civil search

Country-specific civil search support where the international package and country matrix allow it.

CIVIL_INTERNATIONAL

Core events

• background_check.updated: General progress update for an in-flight background check.
• background_check.completed: The report is complete and the report URL is available.
• background_check.failed: The check failed terminally and should move into exception handling.
• verification.completed: A verification-order lane completed successfully.
• verification.exception_created: A verification-order lane entered exception handling.
• verification.exception_resolved: A verification-order exception was resolved.
• monitoring.hit_detected: A monitoring hit was detected for an enrolled subject.
• monitoring.billing_cycle_closed: The monitoring billing cycle closed and a billing event was recorded.

Webhook receiver

Keep the receiver thin. Verify the signature, parse the event, persist the transition you care about, and return a `200`. Vuplicity sends `X-Vuplicity-Signature`, `X-Vuplicity-Timestamp`, `X-Vuplicity-Event`, and `X-Vuplicity-Delivery`. Use webhook subscription APIs to inspect deliveries and rotate the signing secret.

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

export async function POST(request: Request) {
  const rawBody = await request.text();
  const verified = verifyVuplicityWebhookSignature({
    payload: rawBody,
    secret: process.env.VUPLICITY_WEBHOOK_SECRET!,
    headers: request.headers,
  });

  if (!verified.valid) {
    return Response.json({ error: 'Invalid Vuplicity webhook signature' }, { status: 400 });
  }

  const event = JSON.parse(rawBody);
  switch (event.type) {
    case 'background_check.updated':
      break;
    case 'background_check.completed':
      break;
    case 'background_check.failed':
      break;
    case 'verification.completed':
      break;
    case 'verification.exception_created':
      break;
    case 'verification.exception_resolved':
      break;
    case 'monitoring.hit_detected':
      break;
    case 'monitoring.billing_cycle_closed':
      break;
  }

  return Response.json({ received: true });
}

Recommended packages

• `basic`: lightweight screening with lower friction
• `essential`: default production package for most hiring flows
• `complete`: broader criminal coverage for higher-trust roles

Typical status flow

Supported lanes

• Employment verification
• Education verification
• Reference verification
• License verification
• DOT and healthcare lanes

Integration rule

Keep the first integration on hosted sessions plus webhooks. Add direct verification-order calls only when your product truly needs a lower-level verification-first workflow and you are prepared to own the recipe details for each verification lane.

Current capabilities

• Automatic monitoring enrollment from hosted screening sessions
• Monitoring hit events
• Billing-cycle closure events
• Outbound webhook notifications

Enable it

• Add `include_monitoring: true` when creating the hosted screening session.
• Read `monitoring_enrollment_id` and `monitoring_status` from completion data.
• Listen for `monitoring.hit_detected` and `monitoring.billing_cycle_closed` afterward.

Operational tooling

Org-scoped platform health

Admin-only operational view for customer organizations.

GET /api/v1/metrics/platform-health

Operational tooling

Global platform health

Super-admin aggregate view for internal operations and support teams.

GET /api/v1/metrics/platform-health-global

Current contract

• Set `X-Vuplicity-Mode: sandbox` on hosted-session creation or direct consent requests.
• Choose `X-Vuplicity-Scenario` with `clear`, `record_found`, `need_info`, `dispute`, or `monitoring_hit`.
• The sandbox path skips live provider calls and live billing while still emitting webhook lifecycle events.
• Lower-level provider runtime overrides are internal super-admin controls, not public headers.

Headers

# Deterministic sandbox
X-Vuplicity-Mode: sandbox
X-Vuplicity-Scenario: clear | record_found | need_info | dispute | monitoring_hit