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 in under 10 minutes. With our server and client-side libraries, you can verify any employee.

Prerequisites#

To make requests to the Truework API, you will need to create an API key for the Truework sandbox environment. It is also recommended that you configure a webhook to get notified when your verification requests have been completed, although doing so is not required for this tutorial.

Initializing Truework.js#

  1. Include the Truework.js script on the page where you want to display the Credentials flow.
<script src="https://js.truework.com/v1/"></script>
  1. On your backend, call the Truework API to initialize a Credentials session. The most minimal request looks like the following:
def my_view():
response = requests.post(
"http://api.truework.com/credentials/",
{
"environment": "sandbox",
"verification": {
"type": "employment-income"
}
},
headers={
"Authorization": f"Bearer {secret_token}"
}
);
return Response(response.json()['token'])
  1. Use the returned token to instantiate the Credentials flow.
<script>
const credentials = Truework.credentials(yourToken);
credentials.open();
</script>

The Truework widget will activate, and the user will be guided through the process. Behind the scenes, a new verification request will be created once the user fills out the necessary information. You'll receive a webhook notification once the request is completed. The webhooks and data use the same format as other Truework products. For guidance on how to set one up, see Configuring a Webhook.

Sandbox#

Coming soon!

Additional Features#

A number of additional options are available to streamline the user experience.

Employee information can be preloaded, reducing the number of questions we’ll need to ask the user. If you have certain information about a user already, we recommend you preload it to remove the need for us to ask for certain fields within the widget experience.

Employer information can be preloaded as well. 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.

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 preloaded employee information#

requests.post(
"http://api.truework.com/credentials/init/",
{
"environment": "sandbox",
"verification": {
"type": "employment-income",
"employee": {
"full_name": "John Smith",
"date_of_birth": "10/10/1996",
"social_security_number": "xxx-xx-xxxx",
"email_address": "johnsmith@truework.com"
},
"employer": {
"name": "Truework",
}
}
},
headers={
"Authorization": f"Bearer {secret_token}"
}
);

Example of callbacks#

<script>
const credentials = Truework.credentials(yourToken);
credentials.onComplete(() => {
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.