Skip to main content

​
Overview

The Transcrypts SDK lets you add employment verification to any web application. Install the package, initialize it with your API key, and call verify() to open a secure iframe-based verification widget — all in a few lines of code.

​
Prerequisites

Before you begin, make sure you have:

​
Installation

Install the transcrypts package using your preferred package manager: 
npm install transcrypts

​
CDN / Script Tag

You can also load the SDK directly via a script tag. This is useful for vanilla JavaScript projects or quick prototyping. 
<script src="https://cdn.jsdelivr.net/npm/transcrypts/dist/index.js" type="module"></script>

​
Quick Start

The following example shows the minimal setup to run an employment verification:
1

Initialize the SDK

Create a new Transcrypts instance with your API key:
import { Transcrypts } from 'transcrypts';

const transcrypts = new Transcrypts({
  apiKey: 'your-api-key',
});
2

Run a verification

Call the verify() method with the required parameters:
const result = await transcrypts.verify({
  ssn: '123-45-6789',
  user: {
    firstName: 'Jane',
    lastName: 'Doe',
    email: 'jane@example.com',
  },
});
3

Handle the result

Check the result to determine the outcome:
if (result.verified) {
  console.log('Verification passed', result.verificationId);
  console.log('Work history:', result.workExperience);
} else if (result.error?.code === 'USER_CLOSED') {
  console.log('User dismissed the widget');
} else {
  console.error('Verification failed', result.error);
}
Calling verify() opens a full-screen overlay containing the Transcrypts widget. The returned promise resolves when the user completes or closes the verification flow.

​
Configuration Options

Pass these options when creating a new Transcrypts instance:
OptionTypeRequiredDefaultDescription
apiKeystringYes—Your Transcrypts API key.
widgetUrlstringNohttps://widget.transcrypts.comURL of the hosted verification widget.
containerStylePartial<CSSStyleDeclaration>NoFull-screen centered overlayCustom CSS styles for the widget overlay container.

​
Verify Options

Pass these options when calling transcrypts.verify():
OptionTypeRequiredDescription
ssnstringYesThe Social Security Number to verify.
user.firstNamestringNoPre-fill the user’s first name.
user.lastNamestringNoPre-fill the user’s last name.
user.emailstringNoPre-fill the user’s email address.

​
Listening to Events

Use the .on() method to subscribe to widget lifecycle events. It returns an unsubscribe function. 
const transcrypts = new Transcrypts({ apiKey: 'your-api-key' });

// Subscribe to an event
const unsubscribe = transcrypts.on('verification_complete', (event) => {
  console.log('Verification complete:', event.payload);
});

// Later, unsubscribe when no longer needed
unsubscribe();

​
Available Events

EventDescription
readyThe SDK is initialized and ready.
loadedThe widget iframe has finished loading.
verification_startedThe user has started the verification process.
verification_completeVerification completed successfully.
verification_failedVerification encountered an error.
closeThe user closed the widget.
Each event callback receives a TranscryptsEvent object: 
interface TranscryptsEvent {
  type: TranscryptsEventType;
  payload?: Record<string, unknown>;
}

​
Error Handling

The verify() method can resolve with an error state or reject with an exception. Use both a try/catch block and a result check to handle all cases. 
try {
  const result = await transcrypts.verify({ ssn: '123-45-6789' });

  if (result.verified) {
    // Verification succeeded
    console.log('Verified:', result.verificationId);
  } else if (result.error) {
    // The widget returned a structured error
    switch (result.error.code) {
      case 'USER_CLOSED':
        console.log('User dismissed the widget');
        break;
      default:
        console.error('Verification error:', result.error.message);
    }
  }
} catch (err) {
  // An unexpected error occurred (network failure, widget crash, etc.)
  console.error('Unexpected error:', err);
}
The verify() method can both resolve with an error state and reject with an exception. Always use both a try/catch block and a result check.

​
Error Codes

CodeDescription
USER_CLOSEDThe user closed the widget or pressed Escape before completing verification.

​
Common Errors

ErrorCause
Transcrypts: apiKey is requiredThe apiKey option was not provided or is empty.
Transcrypts: ssn is requiredThe ssn option was not provided to verify().

​
Next Steps

SDK Reference

Full API reference for all classes, methods, and types.

Widget & Events

Deep dive into the widget lifecycle and event system.

Framework Examples

Integration examples for React, Vue, Angular, and more.

Architecture

How the iframe-based architecture works.