Truework Direct

Getting started

Truework Direct allows an employee to log into their payroll platform and share their income/employment data directly via Truework Credentials.

The Truework.js widget allows you to embed this employee-driven verification workflow directly in your user-facing application. If the employee cannot login to their payroll provider for any reason, you have the option to still verify any employee in the US with a fallback that leverages Truework Smart Outreach.

Now let’s show you how to get up and running with Truework Direct with Truework.js and Truework Credentials.

This tutorial uses code snippets from the Truework.js examples repository. The Truework.js examples repository contains fully functioning Credentials demo applications using various platforms that you can use to bootstrap your own deployment.

Tutorial

This tutorial will walk you through the following steps to get a basic Truework Direct integration set up:

1Adding Truework.js to your site
2Creating a Truework Direct session and initializing Truework.js
3Listening for updates with webhooks and retrieving report data

This tutorial will use Truework’s sandbox environment. There are a few key differences between Truework’s sandbox and production environments:

  • The sandbox environment does not support co-branding.
  • Credentials verifications in the sandbox environment supports the use of special test SSNs to simulate different scenarios.
  • Credentials verifications in the sandbox environment uses a sign-in screen which accepts any username/password combination.
1

Adding Truework.js to your site

Add the Truework.js script tag to your application’s HTML page(s) as shown below. On page load, Truework.js will be available on the global window.Truework object.

1 <head>
2   <script src="https://js.truework.com/v1"></script>
3 </head>
2

Creating a Truework Direct session and initializing Truework.js

Truework.js must be initialized with a Truework Direct session token that you create on your backend service with the Truework API. This session token will associate the applicant-provided information with your Truework account for later retrieval and use. The process of requesting and retrieving a session token and initializing Truework.js with the token is shown in the diagram below:

Now let’s implement this process.

1

If you haven’t already created a sandbox API key, use Developer Settings to create a new sandbox API key. Your sandbox API key should begin with tw_sk_test_.

2

On your backend, create an API endpoint that calls POST /orders/truework-direct to initialize a Credentials session. The Session Create API generates a token which is returned to your front end client and is used to instantiate Truework.js

1let jsonRequestBodyPayLoad = `
2{
3  "targets": [{
4    "first_name": "Joe",
5    "last_name": "Smith",
6    "social_security_number": "000-20-0000",
7    "contact_email": "joesmith@example.org",
8    "date_of_birth": "1980-01-01",
9    "companies": [{
10      "name": "Example Inc."
11    }],
12    "permissible_purpose": "risk-assessment",
13    "use_case": "mortgage",
14    "type": "employment",
15    "metadata": {
16      "internal_id": "12454"
17    }
18  }]
19}
20`;
21
22app.get("/token", async (req, res) => {
23  const response = await fetch(
24    "https://api.truework-sandbox.com/orders/truework-direct",
25    {
26      method: "POST",
27      headers: {
28        Authorization: `Bearer tw_sk_test_e508eb797edb95ade85284bcb54dd49ed45db1be`,
29        "Content-Type": "application/json",
30      },
31      body: JSON.parse(jsonRequestBodyPayLoad),
32    }
33  );
34
35  res.json(await response.json().truework_direct.targets[0].truework_direct_session_token);
36});
3

If you haven’t already created a sandbox publishable key, use Developer Settings to create a new sandbox publishable key. Your sandbox publishable key should begin with tw_pk_test_.

4

Call the API endpoint created earlier from your frontend and use the returned token to instantiate the Credentials flow.

1<body>
2  <button id="button">Open Credentials Widget</button>
3  <script>
4    document.getElementById("button").addEventListener("click", async () => {
5      const { token } = await fetch("/token").then((res) => res.json());
6      var credentials = Truework.credentials.init({
7        publishableKey:
8          "tw_pk_test_gJbHD7tEwWUoZ8H_KQWKn4rEESHeNhabiosvcij9i0Q", // example key
9        sessionToken: token,
10        env: Truework.credentials.Env.Sandbox,
11      });
12      credentials.open();
13    });
14  </script>
15</body>

The Truework.js widget will activate when the button is clicked and the user will be guided through the Credentials flow. Once the user successfully completes the Credentials flow, you will asynchronously receive updates on the Credentials session through webhooks and fetch the related report data when the data is ready.

3

Listening for updates with webhooks and retrieving report data

Truework uses webhooks to notify you when a Truework Direct session changes state and successfully completes:

  • You’ll receive a credentials_session.state.change webhook when the session successfully completes and a verification report is created.
  • You’ll receive a order.completed webhook when all verifications associated with the order have been completed or canceled.

You can then use the webhook notification of a completed report to fetch the report data, as shown in the diagram below:

Now let’s implement this process.

1

Create an endpoint in your app to receive webhooks sent by Truework.

1app.post("/webhook", require("body-parser").json(), async (req, res) => {
2    if (
3        req.get("X-Truework-Token") === "YOUR_WEBHOOK_TOKEN"
4    ) {
5        console.log("webhook received: ", req.body.hook.event)
6    }
7}
2

Create a new sandbox webhook in Developer Settings, targeting the webhook endpoint you just created. Take note of the token associated with the new sandbox webhook and insert it where YOUR_WEBHOOK_TOKEN is in the example code

3

Once configured, try testing the webhook handler by clicking the “Test” button on the Developer Settings page.

4

Update the webhook handler to fetch the completed report data from the Truework API when the order.completed webhook is received.

We will retrieve the order based on the order_id field of the webhook, and the employment report will be in the verification_requests[].reports list in the API response.

1app.post("/webhook", require("body-parser").json(), async (req, res) => {
2  if (
3    req.get("X-Truework-Token") === "YOUR_WEBHOOK_TOKEN" &&
4    req.body.hook.event === "order.completed"
5  ) {
6    const verification_request_id = req.body.data.order_id;
7    const response = await fetch(
8      `https://api.truework-sandbox.com/orders/${order_id}`,
9      {
10        method: "GET",
11        headers: {
12          Authorization: `Bearer ${YOUR_TRUEWORK_API_KEY}`,
13          "Content-Type": "application/json",
14        },
15      }
16    );
17    console.log(await response.json());
18  }
19  res.send("Ok!");
20});

Moving to production

To promote your sandbox application to production, take the following steps:

1Create a production-mode API key and use this key for all Truework API calls from your backend server.
2Create a production-mode Publishable key and use this key to initialize all Truework.js on your website.
3

Change the base URL for all backend API calls to Truework from https://api.truework-sandbox.com to https://api.truework.com.

1app.get("/token", async (req, res) => {
2    const response = await fetch(
3        "https://api.truework.com/orders/truework-direct",
4        {
5            method: "POST",
6            headers: {
7                Authorization: `Bearer tw_sk_e508eb797edb95ade85284bcb54dd49ed45db1be`, // example key
8                "Content-Type": "application/json",
9            },
10            body: JSON.parse(jsonRequestBodyPayLoad),
11        });
12        res.json(await response.json().truework_direct.targets[0].truework_direct_session_token);
13});
4

Pass the production environment value when instantiating the Credentials session. If the environment value is omitted, the library will default to production.

1  <button id="button">Open Credentials Widget</button>
2  <script>
3    document.getElementById("button").addEventListener("click", async () => {
4      const { token } = await fetch("/token").then((res) => res.json());
5      var credentials = Truework.credentials.init(token, {
6        publishableKey: "tw_pk_gJbHD7tEwWUoZ8H_KQWKn4rEESHeNhabiosvcij9i0Q", // example key
7        sessionToken: token,
8        env: Truework.credentials.Env.Production,
9      });
10      credentials.open();
11    });
12  </script>

Additional features

Callbacks

Callbacks can be configured so that your frontend application can learn about events occurring inside the Credentials flow.

Tracking data can be attached to the request so that your system can associate the verification with the user.

Example of callbacks

1<script>
2  const credentials = Truework.credentials.init({ ... });
3  credentials.onSuccess(() => {
4    console.log("the credentials flow has finished");
5  });
6  credentials.open();
7</script>

Co-branding

Enterprise customers can use Truework Direct co-branding to customize the logo and theme color for each publishable key. Go to your Truework application -> Developer -> Truework.js keys and edit to customize.

Truework Direct co-branding settings

Fallback methods

If the employee doesn’t remember their payroll credentials or is unable to login to their payroll account, Truework.js can be configured to kickstart a verification automatically via Smart Outreach.

The setting to toggle the fallback method on or off can be set when your production access is granted.