Truework Direct API

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:

1<head>
2  <script src="https://js.truework.com/v1"></script>
3</head>
4<body>
5  <button id="verify">Verify</button>
6  <script>
7    document.getElementById('verify').addEventListener('click', async () => {
8      const { token } = await getToken() // depends on implementation
9
10      const direct = Truework.direct.init({
11        publishableKey: 'tw_pk_...',
12        sessionToken: token,
13        env: Truework.direct.Env.Sandbox,
14      });
15
16      direct.onComplete(() => {
17        console.log('Session complete')
18      });
19
20      direct.onError((e) => {
21        console.error('Error', e.code, e.message);
22      });
23
24      await direct.open();
25    });
26  </script>
27</body>

Load the script

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

1<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 finishes the flow, onClose when the widget closes, and onError to handle errors.

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.

1<head>
2    <script src="https://js.truework.com/v1"></script>
3</head>
4...
5<script>
6    (async () => {
7      const { token } = await getToken(); // depends on implementation
8
9      var direct = Truework.direct.init({
10        publishableKey: 'tw_pk_gJbHD7tEwWUoZ8H_KQWKn4rEESHeNhabiosvcij9i0Q', // example key
11        sessionToken: token,
12        env: Truework.direct.Env.Production
13      });
14    })();
15</script>

config object

publishableKey
stringRequired

Publishable key that provides the configuration of this instance of the Truework Direct widget.

sessionToken
stringRequired

Applicant-specific token referencing the Truework Direct session created using the backend API.

env
string enumDefaults to Truework.direct.Env.Production

Environment the session should be initialized in, one of:

ValueEnum object propertyDescription
productionTruework.direct.Env.ProductionFor production publishable keys (tw_pk_), and session tokens created by api.truework.com
sandboxTruework.direct.Env.SandboxFor test publishable keys (tw_pk_test_), and session tokens created by api.truework-sandbox.com
metadata
object

Optional key-value data passed through to the widget (e.g. for internal tracking). Opaque to the widget; use at your discretion.

autoComplete
boolean

Optional. Defaults to true. Controls auto-complete behavior in the widget.

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();).

1const direct = Truework.direct.init(...);
2
3direct.onOpen(() => {
4  console.log("The widget is open!");
5});
6
7direct.onClose(data => {
8  console.log("Widget closed. Tasks:", data.tasks);
9});
10
11// onSuccess is deprecated; use onComplete instead
12direct.onComplete(() => {
13  console.log("Verification flow complete.");
14});
15
16direct.onError(function (e) {
17  console.log("Error", e.code, e.message);
18
19  if (e.code === Truework.direct.ErrorCode.Critical) {
20    /* widget closed */
21  }
22});
23
24await direct.open();
25// some other application logic here...
26await 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:

  • completed (boolean)
  • employer_name (string | null)
  • task_type (string | null)

Use this to show the user which tasks were completed when the widget closes. Returns a function you can call to remove the listener.

Truework.direct.onComplete(fn)

Registers a callback to be called when the user has successfully completed the verification flow. Prefer this over onSuccess. Returns a function you can call to remove the listener.

Truework.direct.onSuccess(fn) (deprecated)

Deprecated. Use onComplete instead. Registers a callback to be called after the flow completes successfully.

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:

ValueEnum object propertyDescription
0Truework.direct.ErrorCode.CriticalCritical error; widget will close.
1Truework.direct.ErrorCode.ErrorGeneral error.
2Truework.direct.ErrorCode.DisplayNon-critical display message.
3Truework.direct.ErrorCode.NetworkNetwork or API failure.
4Truework.direct.ErrorCode.UnauthorizedSession unauthorized.

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:

1direct.onError(function (e) {
2  switch (e.code) {
3    case Truework.direct.ErrorCode.Critical:
4      console.log("A critical Truework Direct error occurred");
5      // widget has closed
6      break;
7    case Truework.direct.ErrorCode.Network:
8      console.log("Network error", e.message);
9      break;
10    default:
11      // handle Error, Display, Unauthorized, etc. as needed
12      break;
13  }
14});

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.