Skip to main content

Verify customers directly from your application using Truework Credentials and Truework.js

Truework Credentials allows an employee to log into their payroll platform and share their income/employment data directly with Truework. Truework.js allows you to embed this employee-driven verification workflow directly in your user-facing application. If the employee doesn't remember their payroll password, you have the option to still verify any employee in the U.S. with a fallback that leverages Truework Smart Outreach.

This page will show you how to get up and running with Truework.js and Truework Credentials. With our server and client-side libraries, you can quickly verify any employee.

Overview#

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.

Sandbox#

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

  1. The sandbox environment does not use real production data for company names
  2. The sandbox environment uses a sign-in screen which accepts any username/password combination

Sandbox mode for Credentials also supports the use of magic SSNs to simulate states that you may encounter in production. To use magic SSNs for Credential sessions, see Testing.

Creating a Publishable Key and API Key#

To instantiate the Truework.js Credentials widget, you will need a Publishable Key generated for the environment in which you're deploying. Publishable keys are used by Truework.js and are not meant to be secret. This means you can safely include publishable keys in public facing code like Javascript/HTML. Please contact your implementation manager to have a publishable key generated for your account.

To make requests to the Truework API, you will need to create an API key for the Truework sandbox environment. API Keys are secret keys and should never be exposed publicly.

Initializing Truework.js#

  1. On your backend, create an API endpoint that calls the Session Create API 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
app.get("/token", async (req, res) => {
const response = await fetch(
"https://api.truework-sandbox.com/credentials/session",
{
method: "POST",
headers: {
"Authorization": `Bearer ${YOUR_TRUEWORK_API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"type": "employment",
"permissible_purpose": "credit-application",
"use_case": "mortgage",
"target": {
"first_name": "Eric",
"last_name": "Bailey",
"social_security_number": "000001234",
"contact_email": "eric@truework.com",
"date_of_birth": "2020-02-02"
}
})
}
);
res.json(await response.json());
});
  1. Add the Truework.js script tag to your application's HTML page(s). On page load, Truework.js will be available on the global window.Truework object.
<head>
<script src="https://js.truework.com/v1"></script>
</head>
  1. Call the API endpoint created in Step 1 from your front end and use the returned token to instantiate the Credentials flow.
<body>
<button id="button">Open Credentials Widget</button>
<script>
document.getElementById("button").addEventListener("click", async () => {
const { token } = await fetch("/token").then((res) => res.json());
var credentials = Truework.credentials.init({
publishableKey:
"tw_pk_test_gJbHD7tEwWUoZ8H_KQWKn4rEESHeNhabiosvcij9i0Q", // example key
sessionToken: token,
env: Truework.credentials.Env.Sandbox
});
credentials.open();
});
</script>
</body>

The Truework 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.

Listening for Webhooks#

Truework uses webhooks to asynchronously update our partners when a Credentials session changes state and successfully completes. Webhooks can be configured from the settings page on Truework.

You'll receive a webhook notification with the event type credentials_session.state.change when the session successfully completes and a verification request is created:

{
"hook": {
"id": 50,
"event": "credentials_session.state.change",
"target": "https://example.com/webhook"
},
"data": {
"state": "success",
"token": "GF7UOlmqj_4X4Sui99qvjc6jA-CHEyyhmQlmJ7yIuoM",
"verification_request_id": "AAAAAAAAAZ0ABz8-Lz-DIPDFfECWdfcOh8GHJQPZGFiSmb1SyxtR2O3z"
}
}

The credentials_session.state.change webhook will contain the verification_request_id needed to fetch the report data from the Get Verifications API. You can poll for completion of the verification request (not recommended), or you can listen for the verification_request.state.change completion event to be notified when the report is ready:

{
"hook": {
"id": 51,
"event": "verification_request.state.change",
"target": "https://example.com/webhook"
},
"data": {
"state": "completed",
"credentials_session_token": "GF7UOlmqj_4X4Sui99qvjc6jA-CHEyyhmQlmJ7yIuoM",
"verification_request_id": "AAAAAAAAAZ0ABz8-Lz-DIPDFfECWdfcOh8GHJQPZGFiSmb1SyxtR2O3z"
}
}

Fetching Verification Request Report Data#

Once the verification request has transitioned to a completed state, you can fetch the employment and income report by calling the Get Verifications API. The employment report will be embedded in the reports field in the API response.

app.post("/webhook", require("body-parser").json(), async (req, res) => {
if (
req.get("X-Truework-Token") === "YOUR_WEBHOOK_TOKEN" &&
req.body.hook.event === "verification_request.state.change" &&
req.body.data.state === "completed"
) {
const verification_request_id = req.body.data.verification_request_id;
const response = await fetch(
`https://api.truework-sandbox.com/verification-requests/${verification_request_id}`,
{
method: "GET",
headers: {
"Authorization": `Bearer ${YOUR_TRUEWORK_API_KEY}`,
"Content-Type": "application/json"
}
}
);
console.log(await response.json());
}
res.send("Ok!");
});

Moving to Production#

To deploy to production, follow the following steps:

  1. Create an API key for the Truework production environment and use this key in all backend API calls
  2. Change the base URL for all backend API calls to Truework from https://api.truework-sandbox.com to https://api.truework.com
  3. Pass the production environment value when instantiating the Credentials session. If the environment value is omitted, the library will default to production
<body>
<button id="button">Open Credentials Widget</button>
<script>
document.getElementById("button").addEventListener("click", async () => {
const { token } = await fetch("/token").then((res) => res.json());
var credentials = Truework.credentials.init(token, {
publishableKey: "tw_pk_gJbHD7tEwWUoZ8H_KQWKn4rEESHeNhabiosvcij9i0Q", // example key
sessionToken: token,
env: Truework.credentials.Env.Production
});
credentials.open();
});
</script>
</body>

Additional Features#

Prefilling Employer Information#

Employer information can be preloaded. Preloading the employer information will allow Truework to bypass asking the employee to search for their employer or payroll system and directly take them to the payroll login screen for their employer. It is preferred that you use Truework's Get Companies API to retrieve a standardized company id to pass the Session Create API.

Example of preloaded target company information#

app.get("/token", async (req, res) => {
const response = await fetch(
"https://api.truework-sandbox.com/credentials/session",
{
method: "POST",
headers: {
"Authorization": `Bearer ${YOUR_TRUEWORK_API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"type": "employment",
"permissible_purpose": "credit-application",
"use_case": "mortgage",
"target": {
"first_name": "Eric",
"last_name": "Bailey",
"social_security_number": "000001234",
"contact_email": "eric@truework.com",
"date_of_birth": "2020-02-02",
"company": {
"id": 5
}
}
})
}
);
res.json(await response.json());
});

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#

<script>
const credentials = Truework.credentials.init({ ... });
credentials.onSuccess(() => {
console.log("the credentials flow has finished");
});
credentials.open();
</script>

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. For more information on Smart Outreach please read Truework Instant and Smart Outreach using the Truework API.

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

Next Steps#

To see more detailed references regarding the requests and responses of various the API endpoints, see the API Docs.

To learn more about different ways that Truework's products can be used together to create complete verification workflows, check out our Implementation Guides.