Implementation Guide

Overview

To quickly implement Truv into your application for employment verification, we recommend following the step-by-step guide below. A diagram and outline is provided with step-by-step implementation details as well.

Sequence Diagram

Below you can see an overview of tokens and data exchange between your application, Truv Bridge, your server/backend, and Truv's API.

1. Request a bridge_token token from your backend
2. On your backend server request bridge token from the Truv's API
3. Initialize Truv Bridge in your application by passing the bridge_token to TruvBridge.init
4. A user successfully connects their account and a public_token is generated. Bridge hands off the public_token client-side via the onSuccess callback.
5. Webhook events start to be delivered once connection status changes.
6. Exchange a temporary public_token for a permanent access_token.
7. Make an API request to Truv to get the data.

19201920

Authentication

Requests to Truv APIs must use HTTPS with TLS 1.2v encryption or higher.

All API requests require the X-Access-Client-Id and X-Access-Secret headers which should contain your Client ID and Access key, respectively. You can find these values in your Dashboard.

Because the values described above may grant access to some or all of your data, you must keep them secret and safe. Do not share them with others in public areas, use them in client-side code or the front end of your application, or otherwise use them in a way that may compromise their security.

Additionally, every API request will use the same base url (https://prod.truv.com) and key, but the prefix for the access key will need to be updated for the environment in use (sandbox, dev, prod).

1. Request a bridge token

Create a Bridge Token including product_type = employment. To Authentication ) and start Bridge you will need your Client ID and API Secret from Dashboard.

curl --request POST \
     --url https://prod.truv.com/v1/bridge-tokens/ \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'X-Access-Client-Id: {{client_id}}' \
     --header 'X-Access-Secret: {{access_key}}' \
     --data '
{
     "tracking_info": "any data for tracking current user",
     "client_name": "Truv Demo",
     "color_primary": "#000000",
     "product_type": "employment",
     "company_mapping_id": "99dd17074ac94aa9ace2621d657c7610",
     "provider_id": "adp",
     "access_token": "99dd17074ac94aa9ace2621d657c7610",
     "user": {
          "id": "12345",
          "first_name": "John",
          "last_name": "Doe",
          "email": "[email protected]",
          "phone": "+14155554193",
          "ssn": "222233333"
     }
}
'

2. Initiate Truv Bridge

Using that Bridge Token, initiate Truv Bridge into your UI by passing the bridge token to TruvBridge.init.

<script src="https://cdn.truv.com/bridge.js"></script>
<script>
  // Step 2 - Call your back end to retrieve a bridge_token from truv
  const bridgeToken = <%= Value returned by API call to acquire bridge_token %>

  // Step 3 - Initialize Bridge
  const bridge = TruvBridge.init({
        bridgeToken: bridgeToken.bridge_token,
    })
</script>

3. Testing Credentials

Test your implementation using sample credentials, refer to Testing or see some sample usernames and passwords below.

Username

Password

Description

goodlogin

goodpassword

Full time current employment

hourly.part-time

goodpassword

Hourly part-time worker

multiple.employments

goodpassword

Multiple employments with different employers

4. Token exchange

Once a user successfully connects their account, a public_token is generated. Bridge will hand off that public_token client-side via the onSuccess or onEvent callback. Note: The public_token will expire after 6 hours.

You will exchange the temporary public_token for a permanent access_token via the Exchange Tokens endpoint. The public_token becomes invalidated once it has been exchanged for an access_token.

{
  "access_token": "48427a36d43c4d5aa6324bc06c692456",
  "link_id": "24d7e80942ce4ad58a93f70ce4115f5c"
}

5. Webhooks

You have the option to receive Webhooks to your server to monitor Task status and get notified when the status of a Task changes. Use link_id or task_id to match the webhook events with Link connections.

{
    "webhook_id": "609a82aab21e4d9ba2569f35e9e8f26a",
    "event_type": "task-status-updated",
    "updated_at": "2021-04-26T13:02:20.369267+00:00",
    "task_id": "67f2924530564282bbaf6d27655e94a4",
    "link_id": "64f8e374949c4b769706028022626bf1",
    "product": "income",
    "tracking_info": "27266f35-bb54-44c3-8905-070641a0c0aa",
    "status": "login"
}

6. Retrieve the data

Using the permanent access_token, you can generate an Employment history report. Alternatively you can use Link ID to pull data from the Employment Data endpoints.

{
  "id": "24d7e80942ce4ad58a93f70ce4115f5c",
  "status": "new",
  "finished_at": "2021-04-06T11:30:00Z",
  "completed_at": "2021-04-06 11:30:00+00:00",
  "access_token": "48427a36d43c4d5aa6324bc06c692456",
  "tracking_info": "user123456",
  "employments": [
    {
      "id": "24d7e80942ce4ad58a93f70ce4115f5c",
      "is_active": false,
      "job_title": "PR associate",
      "job_type": "F",
      "start_date": "2018-01-01",
      "original_hire_date": "2017-06-21",
      "end_date": "2022-06-13",
      "external_last_updated": "2022-06-13",
      "dates_from_statements": false,
      "derived_fields": [
        "is_active"
      ],
      "missing_data_fields": [
        "w2s"
      ],
      "manager_name": "Jenny McDouglas",
      "profile": {
        "first_name": "John",
        "last_name": "Doe",
        "middle_initials": "K",
        "email": "[email protected]",
        "ssn": "123456789",
        "date_of_birth": "1992-03-03",
        "home_address": {
          "street": "1 Morgan Ave",
          "city": "Los Angeles",
          "state": "CA",
          "zip": "90210",
          "country": "US"
        }
      },
      "company": {
        "name": "Facebook Demo",
        "address": {
          "street": "1 Morgan Ave",
          "city": "Los Angeles",
          "state": "CA",
          "zip": "90210",
          "country": "US"
        },
        "phone": "6503087300"
      }
    }
  ],
  "pdf_report": "https://citadelid-resources.s3-us-west-2.amazonaws.com/report.pdf",
  "provider": "adp",
  "data_source": "crawler"
}

Did this page help you?