Getting started

Learn how to get started with Truv

The easiest way to get started with Truv is to run the Quickstart which shows the entire workflow from initializing Bridge to retrieving data via API.

Get API keys

Go to Dashboard and get your Client ID and Sandbox Access key by clicking the Development -> API keys menu item on the left.

You'll have access to three Truv environments. Quickstart runs in the Sandbox environment.




Used for development with test credentials. Unlimited requests and free.


Used for testing your integration with live credentials. Includes 50 free Successful Tasks.


Used for your production environment. All successful Tasks are billed.

Setup Quickstart

Truv can be embedded into your mobile or web app using native WebView components.

Select Quickstart specific for your development environment:


We use Truv-specific terminology in our documentation. To see any definition, either refer to the glossary or hover over the term.

Main concepts

  • Bridge - is a client-side component that your users will interact with in order to link their payroll accounts to Truv.

  • Client ID - is a unique identifier for your team passed into the X-Access-Client-Id header of every API request to authorize it.

  • Access key - is a unique key specific to each of the three environments (Sandbox, Development, Production) passed into the X-Access-Secret header of every API request to authorize it.

  • Link - is a connection to a payroll provider used to retrieve payroll data. Every user who connects to a new payroll provider via Bridge creates a new Link.

  • Task - is a process where a Link is used to pull/write data from/to a payroll provider. For example every income and employment data pull (initial and consequent refreshes) will create a new Task.

  • bridge_token - is a short-lived token provided by the Truv to authorize the use of Bridge. This token has a 6 hour expiration.

  • public_token - is a short-lived token used to exchange for an access_token from the backend. Created after a successful connection to payroll account in the Bridge. This token has a 6 hour expiration.

  • access_token - is a private token unique to a single Link. Used to access Link's data and initiate any actions using the same Link.

Company mappings

Mapping - is a persistent link between employer and payroll provider.

For example, Facebook uses Workday as the payroll provider, so our mapping would link Facebook (employer) to Workday (payroll provider). Generally, companies with mapped payroll providers have higher Conversion than unmapped companies.

Conversion rate

Conversion is the number of successful connection divided by the number of users who engaged with Truv Bridge.

For example, if 100 people click on Truv Bridge and 35 successfully connect their payroll account, then conversion rate is 35%.

Pull through rate

Pull through rate is the number of successful connection divided by the number of users who had an opportunity to engage with Truv Bridge.

For example, if 175 people had an opportunity to connect their payroll account in your UI, but only 100 people saw Truv Bridge by clicking to connect their account, and 35 of those clicks successfully connected, then pull through rate is 20%.

Did this page help you?