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

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.

<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 User as User

    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: order_id, share_url
    API->>User: Email/SMS with verification link
    Note over User: User skips search screens
    User->>User: Lands directly on login page
```

***

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

***

## 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",
  "email": "john@example.com",
  "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",
  "email": "john@example.com",
  "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",
  "email": "john@example.com",
  "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>

***

## Next steps

<CardGroup cols={2}>
  <Card title="Hosted Orders" icon="user-plus" href="/developers/integration/hosted-orders/new-user">
    Create a hosted order from scratch
  </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>