Truework POS Integrations

Verify borrower income directly in your POS application

Prerequisites

Set up a Truework account
Generate a sandbox API Key and Publishable Key under developer settings from your Truework account
Contact implementations@truework.com before implementing to ensure your Publishable Key is configured for your specific workflow and verification methods
Review our [[sandbox-test-cases]]

Implementation steps

1. Create Truework Direct Order

Make a POST request to /orders/truework-direct. Making this POST request creates an order that will contain zero or more verifications, each containing one verification report per employer.

The POST request generates a token that is 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. As a best practice, we additionally recommend sending all companies required to verify a borrower’s employment history.

1 curl --request POST \
2   --url https://api.truework-sandbox.com/orders/truework-direct \
3   --header 'Authorization: Bearer your_sandbox_api_key' \
4   --header 'Content-Type: application/json' \
5   --data '{
6     "targets": [{
7       "first_name": "Joe",
8       "last_name": "Smith",
9       "social_security_number": "000-20-0000",
10       "contact_email": "joesmith@example.org",
11       "date_of_birth": "1980-01-01",
12       "companies": [{"name": "Example Inc."}],
13       "permissible_purpose": "risk-assessment",
14       "use_case": "mortgage",
15       "type": "employment-income",
16       "metadata": {"internal_id": "12454"}
17       "authorization_forms": [
18          {"filename": example.pdf"}]
19   }'

2. Create backend endpoint

Create an API endpoint that calls /orders/truework-direct to create a unique Truework Direct session token.

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

Within the frontend UI (e.g. a button), call the API endpoint you created and use the returned session token to initialize the Truework Direct flow.The Truework.js widget will activate when the button is clicked and the user will be guided through the workflow.

1 <head>
2   <script src="https://js.truework.com/v1"></script>
3 </head>
4 
5 <body>
6   <button id="verify-button">Start Verification</button>
7   <script>
8     document.getElementById("verify-button").addEventListener("click", async () => {
9       const { token } = await fetch("/token").then(res => res.json());
10 
11       const credentials = Truework.credentials.init({
12         publishableKey: "tw_pk_test_your_sandbox_key",
13         sessionToken: token,
14         env: Truework.credentials.Env.Sandbox,
15       });
16 
17       credentials.open();
18     });
19   </script>
20 </body>

Within the target object, it is highly recommended that you specify an action of verify for each company you want the user to verify.

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

4. Webhook configuration

Webhooks can be configured from Developer Settings in the Truework app.

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

Most relevant here are the completed and canceled states. 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.

Order Completed

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

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

Verification State Change

For verifications completed with Smart Outreach, 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: pending-approval → processing → action-required → completed/canceled

5. Retrieve results

To fetch an order, and all verification reports associated with that order, make a GET request to /orders/{order_id}.

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

1 app.post("/webhook", async (req, res) => {
2   if (req.body.hook.event === "order.completed") {
3     const orderId = req.body.data.order_id;
4     const response = await fetch(`https://api.truework-sandbox.com/orders/${orderId}`, {
5       headers: { Authorization: `Bearer ${YOUR_SANDBOX_API_KEY}` }
6     });
7 
8     const orderData = await response.json();
9     // Process verification_requests[].reports
10   }
11   res.send("OK");
12 });

6. Get report data

Make a GET request to /reports/:verification_report_id using the desired report ID. If you don’t have the report ID, you can also find reports under verification_requests[].reports in the GET /orders/{order_id} response.

For JSON format

1 curl -G https://api.truework-sandbox.com/reports/AAAAAAAAAosABwGqF1AUKAH0... \
2   --header "Accept: application/json" \
3   --header "Authorization: Bearer your_sandbox_api_key" \
4   --data "include_income_analytics=true" \
5   --data "include_report_annotations=true" \
6   --data-urlencode "fields=id,status,employee(positions(start_date),social_security_number)"

For PDF format

1 curl -G https://api.truework-sandbox.com/reports/AAAAAAAAAosABwGqF1AUKAH0... \
2   --header "Accept: application/pdf" \
3   --header "Authorization: Bearer your_sandbox_api_key" \
4   --output report.pdf

7. Reverifying a report

Mortgage verifiers are typically required to reverify employment (no income) within 10 days of closing. The Truework API has built in support for this use case for reports that were successfully completed within the last 90 days.

There are two options available to reverify a report - work with your Implementation Manager to determine the best fit for your workflow.

Option 1: POS task workflow (recommended)

If you have the ability to add a task or direct the borrower back to the online application, you can embed the reverification workflow directly in your system using Truework.js.

Setup Prerequisite: Register for order.applicant_action_required webhook in sandbox Developer Settings. Contact your Implementation Manager if this option isn’t visible.

Applicant Action Required webhook

1 {
2   "version": "2023-10-30",
3   "hook": {
4     "id": 42,
5     "event": "order.applicant_action_required",
6     "target": "https://example.com/hook",
7     "triggered_at": "2024-01-30T00:00:00.000Z"
8   },
9   "data": {
10     "order_id": "AAAAAA_some_order_id",
11     "truework_direct_session_token": "tjs_some_token",
12     "metadata": {
13       "key": "value"
14     }
15   }
16 }

Alternative: Get Session Token from API

1 curl -G https://api.truework-sandbox.com/orders/{order_id} \
2   --header "Authorization: Bearer your_sandbox_api_key"

Response

1 {
2   "reverification": {
3     "parent_order_id": "AAAAAA_some_id",
4     "targets": [{
5       "first_name": "John",
6       "last_name": "Doe",
7       "truework_direct_session_token": "tjs_some_token"
8     }]
9   }
10 }

Testing scenarios

Scenario 1: Connection lost (action required)

Complete verification with SSN 000-22-0000
Create reverification from returned report
Receive order.applicant_action_required webhook
Use session token to reinitialize Truework.js widget

Scenario 2: Connection active (seamless)

Complete verification with SSN 000-23-0000
Create reverification from returned report
No webhook needed - reverification completes automatically

Option 2: Email Workflow

If Option 1 is not viable for your workflow, Truework can send an email to the borrower to complete the reverification process outside your online application.

1 curl -X POST https://api.truework-sandbox.com/orders/reverification \
2   --header "Accept: application/json" \
3   --header "Request-Sync: async" \
4   --header "Authorization: Bearer your_sandbox_api_key" \
5   --header "Content-Type: application/json" \
6   --data '{
7     "report_id": "AAAAAAAAAKsAAYJIcQvm1nwU0xBbfC1Yh4qyqjvLhwt1B9gRmTCHCyW6"
8   }'

Ready to move to Production or have questions?

Reach out to implementations@truework.com or directly to your Integration Manager.