Truework.js API reference

Embedding the Truework widget into your workflow

Truework.js is a JavaScript library that allows you to easily integrate Truework Direct into your online application or web portal, simplifying the process to verify consumer’s income and employment data securely and efficiently.

Use Truework.direct to initialize the widget. Truework.credentials is also supported for backward compatibility, but Truework.direct is the preferred API.

Minimal example

Load the script, create a session token on your backend (see Create a Truework Direct order; that guide focuses on the backend order/token flow and currently shows the legacy Truework.credentials initializer), then initialize and open the widget on the frontend using Truework.direct as shown below:

<head>
  <script src="https://js.truework.com/v1"></script>
</head>
<body>
  <button id="verify">Verify</button>
  <script>
    document.getElementById('verify').addEventListener('click', async () => {
      const { token } = await getToken() // depends on implementation
      const direct = Truework.direct.init({
        publishableKey: 'tw_pk_...',
        sessionToken: token,
        env: Truework.direct.Env.Sandbox,
      });
      direct.onComplete(() => {
        console.log('Session complete')
      });
      direct.onError((e) => {
        console.error('Error', e.code, e.message);
      });
      await direct.open();
    });
  </script>
</body>

Load the script

Include the Truework.js script once on the page where the widget will be used:

<script src="https://js.truework.com/v1"></script>

After the script loads, Truework is available on the global object.

Integration flow

1. Backend: Create a Truework Direct order (POST /orders/truework-direct) and obtain a session token. See Make your first Truework Direct order for how to create an order and get the token; that guide currently uses the legacy Truework.credentials widget initializer, but the order/token creation steps are the same when using Truework.direct.
2. Frontend: Load the script (above), call Truework.direct.init({ publishableKey, sessionToken, env }), then call direct.open().
3. Events: Use onComplete when the user submits the session, onClose when the widget closes, and onError to handle errors. These callbacks drive your UI; they don’t confirm that a verification succeeded. Use webhooks to learn when verifications complete and report data is ready.

Best practices: Use one session token per widget open; do not reuse the same token for multiple opens. Use Truework.direct.Env.Sandbox and sandbox publishable keys for testing.

Truework.direct.init(config)

Initializes the Truework Direct widget. Accepts one required argument, a config object. Returns a widget instance with methods to open/close the widget and subscribe to events.

<head>
    <script src="https://js.truework.com/v1"></script>
</head>
...
<script>
    (async () => {
      const { token } = await getToken(); // depends on implementation
      var direct = Truework.direct.init({
        publishableKey: 'tw_pk_gJbHD7tEwWUoZ8H_KQWKn4rEESHeNhabiosvcij9i0Q', // example key
        sessionToken: token,
        env: Truework.direct.Env.Production
      });
    })();
</script>

config object

Truework.direct object

Represents an initialized instance of the Truework Direct widget. This object has methods to control the widget and subscribe to widget events. All event registration methods return a function you can call to remove the listener (e.g. const removeListener = direct.onComplete(fn); removeListener();).

const direct = Truework.direct.init(...);
direct.onOpen(() => {
  console.log("The widget is open!");
});
direct.onClose(data => {
  const submitted = data.tasks.filter(task => task.status === "submitted");
  console.log("Widget closed. Submitted tasks:", submitted);
});
// onSuccess is deprecated; use onComplete instead
direct.onComplete(() => {
  console.log("Session submitted.");
});
direct.onError(function (e) {
  console.log("Error", e.code, e.message);
  if (e.code === Truework.direct.ErrorCode.Critical) {
    /* widget closed */
  }
});
await direct.open();
// some other application logic here...
await direct.close();

Truework.direct.open()

Opens the widget modal window over the current page. Returns a Promise; you can await direct.open().

Truework.direct.close()

Closes the widget modal window. Returns a Promise; you can await direct.close().

Truework.direct.onOpen(fn)

Registers a callback to be called after the modal window is opened. Returns a function you can call to remove the listener.

Truework.direct.onClose(fn)

Registers a callback to be called when the widget is closed. The callback receives a close payload object: { tasks: TaskStatus[] }. Each TaskStatus has:

• status (string): where the user left this task. One of:
  • submitted: The user finished everything required for this task, for example by logging in to their payroll provider. The report is generated after the widget closes, so it is usually not ready yet.
  • in_progress: The user hasn’t finished this task, for example because they chose to finish later, exited the workflow, or never opened an employer you passed in through the API.
  • failed: The task couldn’t be completed in this session, for example because the login failed, or the user ended the session before finishing it.
  • skipped: The user chose to skip this task.
• completed (boolean): true when the user has nothing left to do on this task, which includes submitted, failed, and skipped tasks. It does not mean the task was verified; use status to tell a submitted task apart from a failed or skipped one.
• employer_name (string | null)
• task_type (string | null)

Use this to show the user where each task stands when the widget closes. Verification results arrive later through webhooks. Returns a function you can call to remove the listener.

Truework.direct.onComplete(fn)

Registers a callback to be called when the user submits the session, e.g. by clicking “I’m done, submit”, when a single-employer session’s task is submitted, or when the widget is reopened for a session that was already submitted. It fires whether or not any task was submitted successfully, so check each task’s status in the onClose payload rather than treating onComplete as a success signal. Prefer this over onSuccess. Returns a function you can call to remove the listener.

Truework.direct.onSuccess(fn) (deprecated)

Deprecated. Use onComplete instead; it behaves the same way.

Truework.direct.onError(fn)

Registers a callback to be called when an error occurs. The callback receives a TrueworkError instance (subclass of Error) with:

• code — an ErrorCode value (see Error handling below)
• message — a string (safe for logging; PII is not exposed)
• name — 'TrueworkError'

Returns a function you can call to remove the listener.

For advanced use, you can also subscribe with the generic on(type, handler) method for events 'open', 'close', 'complete', and 'error'.

Error handling

Truework.direct.onError callbacks are called when:

• Any API errors come from our API
• Handled or unhandled errors from our credentials partners
• Truework.js internal errors

There are two behavioral types:

• Critical errors: The widget closes, then onError is called.
• Non-critical errors: The widget may remain open while onError is called.

The ErrorCode value on the error object obscures the root cause (preventing PII exposure) while letting you handle errors appropriately.

ErrorCode (integer enum)

The error object passed to onError has a code property equal to one of:

For network errors (code === ErrorCode.Network), the widget may attach a more specific NetworkErrorCode on the error object when available, for finer-grained handling.

Example:

direct.onError(function (e) {
  switch (e.code) {
    case Truework.direct.ErrorCode.Critical:
      console.log("A critical Truework Direct error occurred");
      // widget has closed
      break;
    case Truework.direct.ErrorCode.Network:
      console.log("Network error", e.message);
      break;
    default:
      // handle Error, Display, Unauthorized, etc. as needed
      break;
  }
});

Browser support

We do our best to support all recent versions of major browsers.

For the sake of security and providing the best experience to the majority of customers, we do not support browsers that are no longer receiving security updates and represent a small minority of traffic.

• We support the latest 3 versions of the following desktop and mobile browsers: Chrome, Firefox, Safari, and Edge
• Internet Explorer 11 (IE11) support ended on May 15, 2022

Visit our Help Center for more information.