> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truv.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Smart Routing

> Automatically recommend the best verification method based on employer payroll coverage

Route each applicant to the fastest verification path -- payroll, bank transactions, or document upload -- based on their employer's payroll coverage. The system checks coverage via [company search](/api-reference/companies/company_autocomplete_search), recommends a method, and lets the applicant confirm or override.

<Info>
  **Integration pattern:** [Bridge Widget](/developers/integration/bridge-widget/overview) | **Products:** VOIE, Income Insights | **Demo:** [Smart Routing](/developers/demos/consumer-credit/smart-routing)
</Info>

***

## Get started

<Steps>
  <Step title="Run the demo">
    Clone and run the [Smart Routing demo](/developers/demos/consumer-credit/smart-routing) to see the full smart routing flow working locally.

    ```bash theme={null}
    git clone https://github.com/truvhq/demo-apps.git
    cd demo-apps
    npm install && npm start
    ```

    Open `http://localhost:5173`, select **Consumer Credit > Smart Routing**, and walk through a verification using sandbox credentials (`goodlogin` / `goodpassword`).

    See [full setup instructions](/developers/quickstarts-overview#demo-apps) for ngrok and environment configuration.
  </Step>

  <Step title="Understand the API flow">
    The demo follows this sequence:

    1. **Search for employer** -- Your server calls [GET /v1/company-mappings-search/](/api-reference/companies/company_autocomplete_search) to find the applicant's employer. The `success_rate` field in the response determines the recommendation: `high` suggests payroll, `low`/`medium` suggests bank, and no results suggests documents.
    2. **Create a user** -- Your server calls [POST /v1/users/](/api-reference/users/users_create) to create a Truv user.
    3. **Create a bridge token** -- Your server calls [POST /v1/users/{id}/tokens/](/api-reference/bridge-token/users_tokens) with the selected `data_sources` array (`["payroll"]`, `["financial_accounts"]`, or `["docs"]`). Pass `company_mapping_id` for payroll to [deeplink](/developers/integration/bridge-widget/deeplinking) Bridge to the employer.
    4. **Initialize Bridge** -- Your frontend opens [Truv Bridge](/developers/sdks/overview) with the `bridge_token`. The applicant connects their provider.
    5. **Receive webhooks** -- Truv sends a `task-status-updated` [webhook](/api-reference/webhooks) when verification completes. Verify the signature using the `X-Webhook-Sign` header with HMAC-SHA256.
    6. **Retrieve the report** -- For payroll or document methods, fetch the [VOIE report](/api-reference/user-income-and-employment-reports/users_reports) with `POST /v1/users/{user_id}/reports/`. For bank income, fetch the [income insights report](/api-reference/income-insights/income-insights-report-create) with `POST /v1/users/{user_id}/income_insights/reports/`.
  </Step>

  <Step title="Review the code">
    Each step maps to a specific file in the demo. Use these as reference when building your integration.

    | Step                  | Demo file                                                                                                            | API reference                                                                     |
    | --------------------- | -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
    | Employer search       | [`src/components/CompanySearch.jsx`](https://github.com/truvhq/demo-apps/blob/main/src/components/CompanySearch.jsx) | [Company Search](/api-reference/companies/company_autocomplete_search)            |
    | User creation         | [`server/routes/bridge.js`](https://github.com/truvhq/demo-apps/blob/main/server/routes/bridge.js)                   | [POST /v1/users/](/api-reference/users/users_create)                              |
    | Bridge token          | [`server/routes/bridge.js`](https://github.com/truvhq/demo-apps/blob/main/server/routes/bridge.js)                   | [POST /v1/users/{id}/tokens/](/api-reference/bridge-token/users_tokens)           |
    | Bridge initialization | [`src/demos/SmartRouting.jsx`](https://github.com/truvhq/demo-apps/blob/main/src/demos/SmartRouting.jsx)             | [Bridge SDK](/developers/sdks/overview)                                           |
    | Webhook verification  | [`server/webhooks.js`](https://github.com/truvhq/demo-apps/blob/main/server/webhooks.js)                             | [Webhooks](/api-reference/webhooks)                                               |
    | Report retrieval      | [`server/routes/user-reports.js`](https://github.com/truvhq/demo-apps/blob/main/server/routes/user-reports.js)       | [Income reports](/api-reference/user-income-and-employment-reports/users_reports) |
  </Step>
</Steps>

***

## Consumer Credit-specific configuration

### Routing logic

The `success_rate` field from [company search](/api-reference/companies/company_autocomplete_search) drives the recommendation:

| `success_rate` value | Recommended method | `data_sources`           |
| -------------------- | ------------------ | ------------------------ |
| `high`               | Payroll            | `["payroll"]`            |
| `low` / `medium`     | Bank transactions  | `["financial_accounts"]` |
| No results           | Document upload    | `["docs"]`               |

The applicant can always override the recommendation and pick any method.

### Data sources

Control which verification methods Bridge shows by setting the `data_sources` array when creating the bridge token:

```json theme={null}
{
  "product_type": "income",
  "data_sources": ["payroll"],
  "company_mapping_id": "COMPANY_MAPPING_ID"
}
```

For payroll, pass `company_mapping_id` to deeplink Bridge to the employer. For bank income, pass `provider_id` to deeplink to the financial institution. Document upload requires no additional identifier.

### Report types

The report endpoint depends on the method the applicant chose:

| Method            | Report endpoint                                     | Report type                                                                     |
| ----------------- | --------------------------------------------------- | ------------------------------------------------------------------------------- |
| Payroll           | `POST /v1/users/{user_id}/reports/`                 | [VOIE](/api-reference/user-income-and-employment-reports/users_reports)         |
| Bank transactions | `POST /v1/users/{user_id}/income_insights/reports/` | [Income Insights](/api-reference/income-insights/income-insights-report-create) |
| Documents         | `POST /v1/users/{user_id}/reports/`                 | [VOIE](/api-reference/user-income-and-employment-reports/users_reports)         |

***

## Next steps

<CardGroup cols={2}>
  <Card title="Bank Income" icon="building-columns" href="/credit/integration/bank-income">
    Verify income from bank transactions when payroll coverage is low
  </Card>

  <Card title="Payroll Income" icon="briefcase" href="/credit/integration/payroll-income">
    Connect directly to payroll for the highest data quality
  </Card>

  <Card title="Bridge Widget Guide" icon="book-open" href="/developers/integration/bridge-widget/overview">
    Full implementation guide for user creation, bridge tokens, and Bridge initialization
  </Card>

  <Card title="Deeplinking" icon="link" href="/developers/integration/bridge-widget/deeplinking">
    Skip the provider search screen when you already know the employer or bank
  </Card>
</CardGroup>