Skip to main content
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.
Deeplinking is one of the highest-impact conversion improvements you can make. Removing the search step eliminates friction and reduces drop-off.

​
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.
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 with the employer name from your application. 
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'

[
  {
    "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. 
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. 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. 
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"
    }
  ]
}'
This is a best-effort match. For the highest accuracy, use company_mapping_id from the company search endpoint.
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. 
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"
    }
  ]
}'
All providers from the List all data providers endpoint are supported as deeplink targets.

​
Testing deeplinking

Use the Truv Dashboard 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

Always deeplink when possible

If your application collects employer name (nearly every mortgage application does), always resolve and pass company_mapping_id. Each extra screen costs conversion.

Pre-resolve at application time

Call the company mapping API when the borrower enters their employer name in your form. Don’t wait until they open Truv Bridge.

Handle no-match gracefully

If a company mapping isn’t found, fall back to launching Bridge without a deeplink. The user can still search and connect manually.

Cache mapping results

Company mappings don’t change frequently. Cache results for common employers to avoid redundant API calls.

​
Next steps

Embedded Orders

Full embedded orders implementation guide

Search Companies

Find company_mapping_id by employer name

Bridge Widget Deeplinking

Deeplinking for Bridge widget flows

Create Order

Create orders with employer pre-fill