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

# Deeplinking

> Pre-fill account information (employer, bank, etc.) to skip search steps and maximize conversion

Deeplinking lets you pre-fill account information (employer, bank, or other provider) when creating an order, bypassing the search screens entirely. When you already know the user's provider, deeplinking sends them directly to the login screen.

<Tip>
  **Deeplinking is one of the highest-impact conversion improvements you can make.** Removing the search step eliminates friction and reduces drop-off.
</Tip>

```mermaid theme={null}
sequenceDiagram
    participant Server as Your Server
    participant API as Truv API
    participant Bridge as Truv Bridge

    Server->>API: Search company mapping (GET /v1/company-mappings-search/)
    API-->>Server: company_mapping_id
    Server->>API: Create order with company_mapping_id
    API-->>Server: bridge_token
    Note over Bridge: User skips search screens
    Bridge->>Bridge: User lands on login page
```

***

## How it works

Truv Bridge normally shows two search screens before login:

1. **Employer selection**: user searches for their employer by name
2. **Provider selection**: user selects their payroll provider (e.g. ADP, Workday)

With deeplinking, you provide this information when creating the order and users land directly on the credential entry screen.

***

## Deeplink by employer

Use this when you know the user's employer name. Truv maps the employer to the correct payroll provider automatically.

### Find the company mapping

Call the [Search companies endpoint](/api-reference/companies/company_mapping) with the employer name from your application.

```bash theme={null}
curl --request GET \
     --url 'https://prod.truv.com/v1/company-mappings-search/?query=Facebook' \
     --header 'X-Access-Client-Id: YOUR_TRUV_CLIENT_ID' \
     --header 'X-Access-Secret: YOUR_TRUV_CLIENT_SECRET'
```

```json theme={null}
[
  {
    "company_mapping_id": "48427a36d43c4d5aa6324bc06c692456",
    "name": "Facebook",
    // ...
  }
]
```

### Create an order with the mapping

Pass the `company_mapping_id` in the `employers` array when creating the order.

```bash theme={null}
curl --request POST \
     --url https://prod.truv.com/v1/orders/ \
     --header 'X-Access-Client-Id: YOUR_TRUV_CLIENT_ID' \
     --header 'X-Access-Secret: YOUR_TRUV_CLIENT_SECRET' \
     --header 'Content-Type: application/json' \
     --data '{
  "products": ["income"],
  "first_name": "John",
  "last_name": "Doe",
  "employers": [
    {
      "company_mapping_id": "48427a36d43c4d5aa6324bc06c692456"
    }
  ]
}'
```

The user skips the employer search screen and lands directly on the provider login page.

### Alternative: Deeplink by company name

If you don't have a `company_mapping_id` but have the employer name on hand, pass `company_name` instead. Truv will attempt to match the employer automatically.

```bash theme={null}
curl --request POST \
     --url https://prod.truv.com/v1/orders/ \
     --header 'X-Access-Client-Id: YOUR_TRUV_CLIENT_ID' \
     --header 'X-Access-Secret: YOUR_TRUV_CLIENT_SECRET' \
     --header 'Content-Type: application/json' \
     --data '{
  "products": ["income"],
  "first_name": "John",
  "last_name": "Doe",
  "employers": [
    {
      "company_name": "facebook"
    }
  ]
}'
```

<Note>
  This is a best-effort match. For the highest accuracy, use `company_mapping_id` from the [company search endpoint](/api-reference/companies/company_autocomplete_search).
</Note>

***

## Deeplink by provider

Use this when you know the specific payroll provider (e.g. ADP, Workday, Gusto) but not the specific employer. Pass the `provider_id` in the `employers` array.

```bash theme={null}
curl --request POST \
     --url https://prod.truv.com/v1/orders/ \
     --header 'X-Access-Client-Id: YOUR_TRUV_CLIENT_ID' \
     --header 'X-Access-Secret: YOUR_TRUV_CLIENT_SECRET' \
     --header 'Content-Type: application/json' \
     --data '{
  "products": ["income"],
  "first_name": "John",
  "last_name": "Doe",
  "employers": [
    {
      "provider_id": "adp"
    }
  ]
}'
```

<Note>
  All providers from the [List all data providers endpoint](/api-reference/data-providers/providers-list) are supported as deeplink targets.
</Note>

***

## Testing deeplinking

Use the [Truv Dashboard Emulator](https://dashboard.truv.com/app/emulator) to test deeplinks before deploying. Enter a `company_mapping_id` or `provider_id` in the emulator settings to verify the user lands on the correct screen.

***

## Best practices for conversion

<CardGroup cols={2}>
  <Card title="Always deeplink when possible" icon="bolt">
    If your application collects employer name (nearly every mortgage application does), always resolve and pass `company_mapping_id`. Each extra screen costs conversion.
  </Card>

  <Card title="Pre-resolve at application time" icon="clock">
    Call the company mapping API when the borrower enters their employer name in your form. Don't wait until they open Truv Bridge.
  </Card>

  <Card title="Handle no-match gracefully" icon="circle-exclamation">
    If a company mapping isn't found, fall back to launching Bridge without a deeplink. The user can still search and connect manually.
  </Card>

  <Card title="Cache mapping results" icon="database">
    Company mappings don't change frequently. Cache results for common employers to avoid redundant API calls.
  </Card>
</CardGroup>

***

## Next steps

<CardGroup cols={2}>
  <Card title="Embedded Orders" icon="window-maximize" href="/developers/integration/embedded-orders/overview">
    Full embedded orders implementation guide
  </Card>

  <Card title="Search Companies" icon="magnifying-glass" href="/api-reference/companies/company_mapping">
    Find `company_mapping_id` by employer name
  </Card>

  <Card title="Bridge Widget Deeplinking" icon="link" href="/developers/integration/bridge-widget/deeplinking">
    Deeplinking for Bridge widget flows
  </Card>

  <Card title="Create Order" icon="file-plus" href="/api-reference/orders/orders_create">
    Create orders with employer pre-fill
  </Card>
</CardGroup>