> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://www.truework.com/docs/guides/mortgage/mortgage-los/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://www.truework.com/_mcp/server.

# Truework LOS Integrations

## Automate verification workflows directly in your LOS application

## Prerequisites

- Set up a [Truework account](https://app.truework.com/requester/signup)
- Generate a sandbox API Key under [developer settings](https://app.truework.com/requester/developer-settings) from your Truework account
- Note our [Sandbox test cases](/docs/api-reference/sandbox)

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

```curl
curl -X POST https://api.truework-sandbox.com/orders/target-employer \
  --header "Accept: application/json" \
  --header "Authorization: Bearer your_sandbox_api_key" \
  --header "Content-Type: application/json" \
  --data '{
    "permissible_purpose": "child-support",
    "target": {
      "company": {
        "name": "Acme Inc"
      },
      "first_name": "Jane",
      "last_name": "Doe",
      "contact_email": "jane@example.com",
      "social_security_number": "000-00-0000"
    },
    "type": "employment-income",
    "use_case": "mortgage"
  }'
```

### 2. Webhook configuration

Webhooks can be configured from [Developer Settings](https://app.truework.com/requester/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.

```json
{
  "hook": {
    "event": "order.completed",
    "target": "https://example.com/webhook"
  },
  "data": {
    "order_id": "AAAAAAAAAosABwGqF1AUKAH0..."
  }
}
```

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

```javascript
app.post("/webhook", async (req, res) => {
  if (req.body.hook.event === "order.completed") {
    const orderId = req.body.data.order_id;
    const response = await fetch(`https://api.truework-sandbox.com/orders/${orderId}`, {
      headers: { Authorization: `Bearer ${YOUR_SANDBOX_API_KEY}` }
    });

    const orderData = await response.json();
    // Process verification_requests[].reports
  }
  res.send("OK");
});
```

### 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

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

#### For PDF format

```curl
curl -G https://api.truework-sandbox.com/reports/AAAAAAAAAosABwGqF1AUKAH0... \
  --header "Accept: application/pdf" \
  --header "Authorization: Bearer your_sandbox_api_key" \
  --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`.

```curl
curl -X POST https://api.truework-sandbox.com/orders/reverification \
  --header "Accept: application/json" \
  --header "Request-Sync: async" \
  --header "Authorization: Bearer your_sandbox_api_key" \
  --header "Content-Type: application/json" \
  --data '{
    "report_id": "AAAAAAAAAKsAAYJIcQvm1nwU0xBbfC1Yh4qyqjvLhwt1B9gRmTCHCyW6"
  }'
```

### 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](mailto: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](mailto:implementations@truework.com) or directly to your Integration Manager.