Quickstart

Learn how to get started with Truv

Don't want to write code? Check out the Truv Postman Collection for a no-code way to get started with Truv's API.

Introduction

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

Sign up for the Dashboard and get your keys. You'll have two different API keys, and there are three different Truv environments. Today we'll start in the Sandbox environment.

client_idPrivate identifier for your team
access_keyPrivate key, one for each of the three environments

Get Client ID and Access key by clicking the Development -> API keys menu item in the Dashboard.

EnvironmentDescription
SandboxUsed for development with test credentials. Unlimited requests and free.
DevelopmentUsed for testing your integration with live credentials. Includes 50 free Successful Tasks.
ProductionUsed for your production environment. All successful Tasks are billed.

If you are stuck at any point in the Quickstart, shoot us an email at [email protected]

Setup

Once you have your API keys, it is time to run Truv Quickstart locally! The Quickstart shows the entire workflow from initializing the Bridge to retrieving data. It contains code examples in some of the most popular languages: NodeJS, Python, Ruby, C# and Go.

For mobile platforms, we have separate Quickstart apps for iOS and Android.

The instructions below will guide you through the process of cloning the Quickstart repository, customizing the .env file with your Truv client ID and Access Key, and finally, building and running the app.

# Clone the Quickstart repository
git clone https://github.com/truvhq/quickstart.git

# Open Quickstart
cd quickstart

# Create .env file 
make env

# Update the values in .env file by adding in your Client ID and Sandbox Access key. 
#API_CLIENT_ID=<Your Client ID here>
#API_SECRET=<Your Access key here>

# Also, in .env uncomment the line with API_PRODUCT_TYPE that you want to use
#API_PRODUCT_TYPE=employment

# Run the make script for your coding language
make python_local
# Clone the Quickstart repository
git clone https://github.com/citadelid/quickstart.git

# Open Quickstart in your coding language
cd quickstart/python

# Copy the .env.example file to a new file in the same directory and name it .env. 
cp .env.example .env

# Update the values adding in the your Client ID and Sandbox Access key. 
#API_CLIENT_ID=<Your Client ID here>
#API_SECRET=<Your Access key here>
# Uncomment the line with API_PRODUCT_TYPE that you want to use
#API_PRODUCT_TYPE=employment

#Run the make script for your coding language
make python_docker
/*
Clone the Quickstart repository:
git clone https://github.com/truvhq/quickstart-ios.git

Open Quickstart:
cd quickstart-ios

Create constants file:
touch truv-quickstart/Constants.swift
*/
import Foundation

var TruvClientID = "<client_id>"
var TruvClientSecret = "<access_key>"
var TruvAPIUrl = "https://prod.truv.com/v1/"
var TruvProductType = "<employment or income>"

/*
Open the project in XCode and run the app
*/
/*
Clone the Quickstart repository:
git clone https://github.com/truvhq/quickstart-android.git

Open Quickstart:
cd quickstart-android

Create constants file:
touch local.properties
*/

truvClientId="<client_id>"
truvSecret="<access_key>"
truvApiUrl="https://prod.truv.com/v1/"
truvProductType="<employment or income>"

/*
Open the project in Android Studio and run the app
*/

Your app will be running at http://localhost:5000 (for mobile apps it will launch in Xcode or Android Studio respectively).

Create your first Link

Most API requests interact with a Link, which is a Truv term for a login attempt at a payroll provider, work account, or financial institution. A single end-user of your application might have accounts at different providers, which means they would have different Links. A Link is not the same as a payroll account, although every account will be associated with a Link. For example, if a user has one login at their provider that was used for payroll in their two most recent employments, a single Link would be used to access data for both. A link represents an end-user's credentials and holds enough context to allow Truv to access a payroll provider on behalf of the end-user.

Now that you have the Quickstart running, you’ll add your first Link in the Sandbox environment. Once you’ve opened the Quickstart app, click the Connect button and follow the instructions in the Bridge.

Use the Sandbox credentials to simulate a successful login:

username: goodlogin
password: goodpassword
If prompted to enter a 2FA code: 12345

The Sandbox environment is designed to allow you to log in with multiple credentials that provide different data scenarios.

When you click Done at the end of a Bridge session you will be able to see the data returned by Truv.

How it works

The Truv flow begins when your user wants to connect their payroll account to your app. Both a server and a client-side component are used to access the Truv APIs. The flow looks like this:

The first step is to create a new bridge_token by making a Create Bridge Token request and passing in the required parameters. This bridge_token is a short-lived, one-time use token that authenticates your app with the Truv Bridge. Several of the environment variables you configured when launching the Quickstart, such as product_type, are used as parameters for the bridge_token.

❗️

Never place or use your Client ID or Access key in your application's front end.

def get_bridge_token(self) -> Any:
        """
        :param public_token:
        :return:
        """
        class BridgeTokenRequest(TypedDict):
            product_type: str
            client_name: str
            tracking_info: str
        request_data: BridgeTokenRequest = {
            'product_type': self.PRODUCT_TYPE,
            'client_name': 'Truv Quickstart',
            'tracking_info': '1337'
        }
        tokens: Any = requests.post(
            self.API_URL + 'bridge-tokens/',
            json=request_data,
            headers=self.API_HEADERS,
        ).json()
        return tokens

Once you have a bridge_token, you can use it to initialize the Bridge. The Bridge is a drop-in, client-side module available for web clients, iOS, and Android that handles the authentication process. Quickstart uses the Bridge on the web, which is a pure JavaScript integration that you trigger via your client-side code. This is what your users use to log into their payroll accounts.

The application front-end runs TruvBridge.init, passing the bridge_token returned from the application back-end and assigning callback functions.

const bridge = TruvBridge.init({
  bridgeToken: bridgeToken.bridge_token,
  onLoad: function() { ... },
  onSuccess: function(public_token, meta) { ... },
  onEvent: function(event_type, payload) { ... },
  onClose: function() { ... }
});
window.bridge = bridge;

After a user submits their credentials within the Bridge, it provides you with a public_token via the onSuccess callback. The code below shows how Quickstart passes the public_token from the client-side code to the server.

onSuccess: async function (token) {
  console.log('token: ', token);
  successClosing = true
  const content = document.querySelector('.spinnerContainer');
  content.classList.remove('hidden');
  let verificationInfo;
  try {
    verificationInfo = await apiRequests.getVerificationInfoByToken(token);
  } catch(e) {
    console.error(e)
    content.classList.add('hidden');
    return;
  }
  content.classList.add('hidden');
  if (!verificationInfo.length) {
    return;
  }
},
...
onClose: function () {
  console.log('closed');
  if (successClosing !== true) {
    renderEmploymentHistory([{ company: { address: {} } }]);
  }
},

📘

public_token is temporary and expires after 6 hours

Next, on the server side, the Quickstart calls Link Exchange Tokens to obtain an access_token and a link_id, as illustrated in the code excerpt below. Both access_token and link_id uniquely identify a Link and are required arguments for most Truv API endpoints. In your code, you'll need to securely store your access_token and link_id to make API requests for that Link.

def get_access_token(self, public_token: str) -> str:
        """
        https://docs.truv.com/?python#exchange-token-flow
        :param public_token:
        :return:
        """
        logging.info("TRUV: Exchanging a public_token for an access_token from https://prod.truv.com/v1/link-access-tokens")
        logging.info("TRUV: Public Token - %s", public_token)
        class AccessTokenRequest(TypedDict):
            public_token: str
        class AccessTokenResponse(TypedDict):
            access_token: str
            link_id: str
        request_data: AccessTokenRequest = {
            'public_token': public_token,
        }
        tokens: AccessTokenResponse = requests.post(
            self.API_URL + 'link-access-tokens/',
            json=request_data,
            headers=self.API_HEADERS,
        ).json()
        return tokens['access_token']

Making API requests

Now that we've gone over the Bridge flow and token exchange process, we can explore how to pull the report for a successful connection. As an example, we'll look at Quickstart's call to Income and employment report, which retrieves the full employment and income report, including profile, company, and employment information.

    def get_income_info_by_token(self, access_token: str) -> Any:
    """
    :param access_token:
    :return:
    """

    class VerificationRequest(TypedDict):
        access_token: str

    request_data: VerificationRequest = {'access_token': access_token}
    return requests.post(
        self.API_URL + 'link/reports/income/',
        json=request_data,
        headers=self.API_HEADERS,
    ).json()

Example response data:

{
  "id": "24d7e80942ce4ad58a93f70ce4115f5c",
  "status": "new",
  "completed_at": "2021-04-06 11:30:00+00:00",
  "access_token": "48427a36d43c4d5aa6324bc06c692456",
  "tracking_info": "user123456",
  "refresh_status": "new",
  "employments": [
    {
      "id": "24d7e80942ce4ad58a93f70ce4115f5c",
      "job_title": "PR associate",
      "job_type": "F",
      "start_date": "2018-01-01",
      "end_date": "2019-08-24",
      "external_last_updated": "2019-08-24",
      "original_hire_date": "2017-06-21",
      "is_active": false,
      "dates_from_statements": false,
      "derived_fields": [
        "is_active"
      ],
      "missing_data_fields": [
        "w2s"
      ],
      "profile": {
        "first_name": "John",
        "last_name": "Doe",
        "middle_initials": "K",
        "ssn": "123456789",
        "email": "[email protected]",
        "date_of_birth": "1992-03-03",
        "home_address": {
          "street": "1 Morgan Ave",
          "city": "Los Angeles",
          "state": "CA",
          "zip": "90210"
        }
      },
      "company": {
        "name": "Facebook Demo",
        "address": {
          "street": "1 Hacker Way",
          "city": "Menlo Park",
          "state": "CA",
          "zip": "94025"
        },
        "phone": "6503087300"
      },
      "income": "70000.00",
      "income_unit": "YEARLY",
      "pay_frequency": "M",
      "manager_name": "Jenny McDouglas",
      "statements": [
        {
          "id": "24d7e80942ce4ad58a93f70ce4115f5c",
          "pay_date": "2018-05-15",
          "net_pay": "11500.32",
          "net_pay_ytd": "31980.64",
          "gross_pay": "13900.11",
          "gross_pay_ytd": "49200.00",
          "bonus": "100.00",
          "commission": "12000.00",
          "hours": "40.00",
          "basis_of_pay": "S",
          "period_start": "2018-05-01",
          "period_end": "2018-05-15",
          "regular": "1695.11",
          "regular_ytd": "23000.00",
          "bonus_ytd": "1000.00",
          "commission_ytd": "24000.00",
          "overtime": "45.00",
          "overtime_ytd": "500.00",
          "other_pay": "60.00",
          "other_pay_ytd": "700.00",
          "earnings": [
            {}
          ],
          "earnings_ytd": [
            {}
          ],
          "deductions": [
            {}
          ],
          "deductions_ytd": [
            {}
          ],
          "md5sum": "03639d6a6624f69a54a88ea90bd25e9d",
          "file": "https://citadelid-resources.s3-us-west-2.amazonaws.com/paystub_sample.pdf"
        }
      ],
      "annual_income_summary": [
        {
          "id": "24d7e80942ce4ad58a93f70ce4115f5c",
          "year": 2018,
          "regular": "23000.00",
          "bonus": "1000.00",
          "commission": "24000.00",
          "overtime": "500.00",
          "other_pay": "700.00",
          "net_pay": "31980.64",
          "gross_pay": "49200.00"
        }
      ],
      "bank_accounts": [
        {
          "account_number": "1234567890",
          "routing_number": "123456789",
          "account_name": "My Bank",
          "account_type": "C",
          "deposit_type": "A",
          "deposit_value": "200.00",
          "bank_name": "TD Bank"
        }
      ],
      "annual_salary": "70000.00",
      "hourly_salary": "36.40",
      "w2s": [
        {
          "file": "https://citadelid-resources.s3-us-west-2.amazonaws.com/W2_sample.pdf",
          "md5sum": "f65e30c39124ad707ac4b3aeaee923a7",
          "year": 2020
        }
      ]
    }
  ],
  "provider": "adp"
}

Next steps

Congratulations, you have completed the Truv Quickstart! From here, we invite you to modify the Quickstart code to get more practice with the Truv API.

If you're not sure which products you want to use, check out the guides.

If you do know which product you want, you can go directly to its documentation. Products documented here are Income and Employment, Employment History, Direct Deposit Switch, and Paycheck Linked Loans.

Quickstart covered working with web apps. If your Truv app will be on mobile, see the Bridge SDK to learn about getting started with mobile client-side setup.

For more demo apps, including apps demonstrating real-world examples, see sample apps.