Skip to main content
Pre-fill account information (employer, bank, or other provider) when creating a hosted order to bypass the search screens. When the user clicks the verification link, they land directly on 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’s hosted verification page 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",
  "email": "john@example.com",
  "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",
  "email": "john@example.com",
  "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",
  "email": "john@example.com",
  "employers": [
    {
      "provider_id": "adp"
    }
  ]
}'
All providers from the List all data providers endpoint are supported as deeplink targets.

​
Next steps

Hosted Orders

Create a hosted order from scratch

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