Truework LOS Integrations

Automate verification workflows directly in your LOS application

Prerequisites

• Set up a Truework account
• Generate a sandbox API Key under developer settings from your Truework account
• Note our [[sandbox-test-cases]]

Implementation Steps

1. Create Target Employer Order

To call the Truework API, make an asynchronous POST request to the /orders/target-employer endpoint. Making this POST request creates an order that will contain zero or more verifications, each containing one verification report per employer for the user.

When calling the /orders/target-employer endpoint, although you will receive a response instantly, there will be no reports associated with the verification on the order, and you will need to retrieve the report(s), which is detailed in the next section.

1
curl -X POST https://api.truework-sandbox.com/orders/target-employer \
2
  --header "Accept: application/json" \
3
  --header "Authorization: Bearer your_sandbox_api_key" \
4
  --header "Content-Type: application/json" \
5
  --data '{
6
    "permissible_purpose": "child-support",
7
    "target": {
8
      "company": {
9
        "name": "Acme Inc"
10
      },
11
      "first_name": "Jane",
12
      "last_name": "Doe",
13
      "contact_email": "jane@example.com",
14
      "social_security_number": "000-00-0000"
15
    },
16
    "type": "employment-income",
17
    "use_case": "mortgage"
18
  }'

2. 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

3. 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
});

4. Get report data

To retrieve a specific report, make a GET request to /reports/:verification_report_id using the desired report ID.

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

5. Reverify 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.

To retrieve a report, make a POST request to /orders/reverification.

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
  }'

Additional Recommendations

The following functionality is recommended to enhance your API integration with Truework. For information on the endpoints and functionality, reach out to implementations@truework.com.

1. Get Status Updates

Track order progress through Truework’s verification process and display real-time status updates in your Order Detail screen.

2. Submitting party email address

Attach the submitting party information to a verification request when using a service account. This allows an individual to own the verification, opposed to a service account. The submitting party must have a valid Truework account.

Ready to move to Production or have questions?

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