Overview

The sections below cover each of the data values and configurations for an employment history report. Use the Retrieve an employment history report endpoint to collect the data.

Data structure

Verification Metadata
Employment
Employer
Identity

Field Customization

In the Dashboard, select specific data fields for your API response. Mandatory fields are grayed out and can't be disabled. View the example below.

Example report

The JSON sample below contains a comprehensive response.

{
  "id": "24d7e80942ce4ad58a93f70ce4115f5c",
  "status": "new",
  "completed_at": "2021-04-06 11:30:00+00:00",
  "access_token": "48427a36d43c4d5aa6324bc06c692456",
  "tracking_info": "user123456",
  "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"
      }
    }
  ],
  "provider": "adp"
}

Verification data

The data below refers to employment verification.

Name	Type	Description
id	string	Unique ID of the report
status	string	Task status from the Connection Lifecycle
completed_at	string	Timestamp of completed report
access_token	string	Payroll provider Link access_token
tracking_info	string	String value provided when generating `bridge_token`
refresh_status	string	Status of most recent refresh task
provider	string	User connected payroll provider
employments	object	List of employments from payroll provider

Employment data

This table covers payroll provider records for employment.

Name	Type	Description
id	string	Unique ID for an employment
job_title	string (nullable)	Employee's job title
job_type	string (nullable)	Type of employment recorded in payroll provider: `F` - Full Time `P` - Part Time `S` - Seasonal `D` - Daily (per diem) `C` - Contract
start_date	string(date)	Date of employment start
end_date	string(date) (nullable)	Date of employment end
external_last_updated	string(date) (nullable)	Date of last updated employment data from payroll provider
original_hire_date	string(date) (nullable)	Date when employee was originally hired
is_active	boolean (nullable)	Status of active employment
dates_from_statements	boolean (nullable)	Status of determining employee's dates of hire or termination is from first and last pay statements
derived_fields	object (nullable)	Array of derived fields
missing_data_fields	object (nullable)	List of missing payroll API response data fields
company	object (nullable)	Employer information
profile	object (nullable)	Identity information

Employer data

The data below is for payroll provider information for employers.

Name	Type	Description
name	string	Employer name
address	object (nullable)	Employer address
street	string (nullable)	Employer street
city	string (nullable)	Employer city
state	string (nullable)	Employer state
zip	string (nullable)	Employer zip code
phone	string (nullable)	Employer phone number

Identity data

The table below covers the employee's personal information found from the payroll provider.

Name	Type	Description
first_name	string	First name
last_name	string	Last name
middle_initials	string (nullable)	Middle initials
ssn	string (nullable)	Social security number, full or last 4 digits
email	string(email) (nullable)	Personal or work email address
date_of_birth	string(date) (nullable)	Date of birth
home_address	object (nullable)	Home address
street	string (nullable)	Street
city	string (nullable)	City
state	string (nullable)	State
zip	string (nullable)	Zip code

Downloadable PDF Report

When users connect successfully, Truv automatically generates reports. These are available for users to download from the dashboard or through the API.