> 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-pos/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://www.truework.com/_mcp/server.

# Truework POS Integrations

## Verify borrower income directly in your POS application

## Prerequisites

- Set up a [Truework account](https://app.truework.com/requester/signup)
- Generate a sandbox API Key and Publishable Key under [developer settings](https://app.truework.com/requester/developer-settings) from your Truework account
- Contact [implementations@truework.com](mailto:implementations@truework.com) when you are ready to begin implementing to ensure your Publishable Key is configured for your specific workflow and verification methods
- Review our [Sandbox test cases](/docs/api-reference/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.

```bash
curl --request POST \
  --url https://api.truework-sandbox.com/orders/truework-direct \
  --header 'Authorization: Bearer your_sandbox_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "targets": [{
      "first_name": "Joe",
      "last_name": "Smith",
      "social_security_number": "000-20-0000",
      "contact_email": "joesmith@example.org",
      "date_of_birth": "1980-01-01",
      "companies": [{"name": "Example Inc."}],
      "permissible_purpose": "risk-assessment",
      "use_case": "mortgage",
      "type": "employment-income",
      "metadata": {"internal_id": "12454"},
      "authorization_forms": [
        {"filename": "example.pdf"}]
    }]
  }'
```

### 2. Create backend endpoint

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

```javascript
app.get("/token", async (req, res) => {
  const response = await fetch(
    "https://api.truework-sandbox.com/orders/truework-direct",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${YOUR_SANDBOX_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(requestPayload),
    }
  );

  const data = await response.json();
  res.json({ token: data.truework_direct.targets[0].truework_direct_session_token });
});
```

### 3. Launch the Truework.js widget

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.

```html
<head>
  <script src="https://js.truework.com/v1"></script>
</head>

<body>
  <button id="verify-button">Start Verification</button>
  <script>
    document.getElementById("verify-button").addEventListener("click", async () => {
      const { token } = await fetch("/token").then(res => res.json());

      const credentials = Truework.credentials.init({
        publishableKey: "tw_pk_test_your_sandbox_key",
        sessionToken: token,
        env: Truework.credentials.Env.Sandbox,
      });

      credentials.open();
    });
  </script>
</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.

```json
{
  "mode": "truework-direct",
  "targets": [{
    "companies": [{
      "name": "Walmart",
      "action": "verify"
    }, {
      "name": "Amazon",
      "action": "do-not-verify"
    }]
  }]
}
```

### 4. 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": {
    "id": 50,
    "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`

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

```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");
});
```

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

```bash
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

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

```json
{
  "version": "2023-10-30",
  "hook": {
    "id": 42,
    "event": "order.applicant_action_required",
    "target": "https://example.com/hook",
    "triggered_at": "2024-01-30T00:00:00.000Z"
  },
  "data": {
    "order_id": "AAAAAA_some_order_id",
    "truework_direct_session_token": "tjs_some_token",
    "metadata": {
      "key": "value"
    }
  }
}
```

##### Alternative: Get Session Token from API

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

###### Response

```json
{
  "reverification": {
    "parent_order_id": "AAAAAA_some_id",
    "targets": [{
      "first_name": "John",
      "last_name": "Doe",
      "truework_direct_session_token": "tjs_some_token"
    }]
  }
}
```

##### Testing scenarios

###### Scenario 1: Connection lost (action required)

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

###### Scenario 2: Connection active (seamless)

1. Complete verification with SSN `000-23-0000`
2. Create reverification from returned report
3. 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.

```bash
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"
  }'
```

## Ready to move to Production or have questions?

Reach out to [implementations@truework.com](mailto:implementations@truework.com) or directly to your Integration Manager.