Truework Direct API

Make your first Truework Direct order

The Truework Direct Order API enables you to seamlessly integrate the Truework.js widget directly into your frontend, enabling in-app verifications so that consumers don’t have to leave your application to provide verified employment data.

In this guide, we’ll explore how to set up and test creating a Truework Direct Order. Get ready to dive in and make your first request with ease!

Certain features of Truework Direct are not available for testing in the Truework sandbox environment. If this affects your integration, someone from the Truework team can help assist you with testing these features.

Prerequisites

  • Set up a Truework account
  • Generate a sandbox API Key and Publishable Key under developer settings from your Truework account
  • Notify implementations@truework.com when you are ready to begin implementing to ensure your Publishable Key is properly configured based on your workflow as the Publishable Key controls which verification methods are included in your API request

Integrating with the Truework Direct

Creating a Truework Direct order

To get started and initiate your first verification request, you will Create a Truework Direct order. To call the Truework Direct order endpoint, you will need to make a POST request to the /orders/truework-direct endpoint. Making this POST request creates an order that will contain zero or more verifications, each containing one verification report per employer.

Example request

1curl --request POST \
2  --url https://api.truework-sandbox.com/orders/truework-direct \
3  --header 'Accept: application/json' \
4  --header 'Authorization: Bearer 123' \
5  --header 'Content-Type: application/json' \
6  --data '{
7  "loan_id": null,
8  "search_key": null,
9  "targets": [
10    {
11      "authorization_forms": null,
12      "companies": null,
13      "contact_email": "string",
14      "date_of_birth": "1990-05-20",
15      "first_name": "Jane",
16      "last_name": "Doe",
17      "metadata": null,
18      "permissible_purpose": "child-support",
19      "reseller_originating_party": {
20        "originating_party": "string",
21        "permissible_purpose": "child-support",
22        "use_case": "mortgage"
23      },
24      "social_security_number": "000-00-0000",
25      "type": "employment-income",
26      "use_case": "mortgage"
27    }
28  ]
29}'

The POST request also generates a token that will be used to initialize Truework.js, the consumer-facing widget that will enable the user to complete the verification. The token represents a unique instantiation of the widget, including any preloaded employment information.

Initializing the Truework.js widget

On your backend, create an API endpoint that calls the /orders/truework-direct endpoint to initialize a Truework.js session. Use the Truework direct session token from the /orders/truework-direct call to initiate 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 ${YOUR_TRUEWORK_API_KEY}`,
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});

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.

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

Finally, from the front end UI (e.g. button) call the API endpoint you created on your backend and use the returned token to instantiate the Truework Direct 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>

Within the targets object, you may optionally hint to the applicant which companies they should verify or not verify (if you have already verified a company via other means). If you do not know which company the applicant works for and would like them to select it on their own, you may omit the companies field.

1{
2    "mode": "truework-direct",
3    "targets": [{
4        "companies": [
5            {
6                "name": "Walmart",
7                "action": "verify"
8            },
9            {
10                "name": "Amazon",
11                "action": "do-not-verify"
12            }
13        ]
14    }]
15}

The Truework.js widget will activate when the button is clicked and the user will be guided through each of the verification methods enabled for your workflow. Once the user successfully completes their verification, regardless of method, you will asynchronously receive updates through webhooks and can fetch the related report data when the data is ready.

The verification will automatically move through each of the verification methods from Instant > Credentials > Smart Outreach.

Listening for webhooks

Truework uses webhooks to asynchronously update our partners when a verification is completed. Webhooks are configured under developer settings in the Truework app.

There are two types of webhooks: order completed and verification state change.

Order completed webhook

The order.completed webhook will be issued when all employer verifications associated with the order have been completed or canceled. Once you receive this webhook, you can fetch the order results.

1{
2  "hook": {
3    "id": 50,
4    "event": "order.completed",
5    "target": "https://example.com/webhook"
6  },
7  "data": {
8    "order_id": "AAAAAAAAAosABwGqF1AUKAH0-puth1tCzLNar3Jyb4bx3wdVKU99XC26",
9  }
10}

Verification state change webhook

With Smart Outreach verifications, you’ll likely need more granular updates about the data contained within an order. The verification_request.state.change webhook is issued when a verification request in the order changes state.

States of note include pending-approval, processing, action-required, completed, and canceled.

Of interest will mostly be the states completed and canceled:

  • A completed state indicates that new data is now available on the order
  • A canceled state indicates that a verification was not able to be completed, but may have user-provided information and/or documents

If a verification reaches Smart Outreach, it can hit an action-required state, indicating that more information is required to process the request. Additional information required can be found in the Truework app.

Receiving report data

Once an order.completed webhook is received, to fetch an order, and all verification reports associated with that order, make a GET request to /orders/{order_id}.

The employment report(s) will be in the verification_requests[].reports list in the API response.

Moving to production

A general API service account is recommended to manage the integration (e.g. truework@yourcompany.com).

When your integration is complete (or nearing completion), follow the steps below:

  • Generate your production API Key and Publishable Key under developer settings from your Truework account
  • Notify implementations@truework.com you are ready to move to production at least three (3) days prior to the target go live date

Questions?

Not a problem, we are here to help! Send your questions to implementations@truework.com.