Verifications Overview

A Verification is used to retrieve information about an employee's occupation and compensation. The individual requesting the verification is referred to as the Verifier, and the individual who is being verified is referred to as the Target. Truework offers two types of Verifications:

note

Verification of Employment (VOE)

A report that contains the Target's position, start and end dates at a given employer.

note

Verification of Income (VOI)

Includes all information provided in a VOE along with the Target's salary and earnings over the last three years.

Models

Verification

PROPERTY	TYPE	NULLABLE	DESCRIPTION
id	string		The id of the verification request
created	string		Creation date of verification request in ISO 8601 format
type	Type		Type of verification report
permissible_purpose	PermissiblePurpose		Reason for why this verification is being conducted
state	State		State of the verification request
target	Target		Information about the verification request target
price	Price		Billing information about how much the verification request will cost once completed
turnaround_time	TurnaroundTime		Expected turnaround time in hours for the verification request; will be an empty if an estimate does not exist for the verification request
use_case	UseCase		Use case for this request
date_of_completion	string		The date when this verification was completed in ISO 8601 format
loan_id	string		The loan_id associated with the verification request
cancellation_reason	string		The reason for the cancellation of the request; only present when state is canceled
cancellation_details	string		The details for the cancellation; only present when state is canceled and available
documents	Document[]		Supporting documentation files provided by the verifier for the verification
reports	Report[]		Applicable reports belonging to this request, if the request has been completed
metadata	JSON		A single level key-value JSON object that can be used to store custom data on the verification request; keys and values must be strings
request_parameters	RequestParameters		Details regarding how the verification will be or has been processed

Target

PROPERTY	TYPE	NULLABLE	DESCRIPTION
first_name	string		First name of the target
last_name	string		Last name of the target
social_security_number	string		The target's social security number in format ***-**-XXXX
company	Company		Details about the target's company
contact_email	string		Target's email address
date_of_birth	string		Target's date of birth in format YYYY-MM-DD

Company

PROPERTY	TYPE	NULLABLE	DESCRIPTION
name	string		The name of the company
id	string		The id returned in a company search response
phone_number	string		Contact phone number for this company
address	string		Street address of the company
city	string		City of the company
state	string		State of the company
zip_code	string		Zip code of the company

Price

PROPERTY	TYPE	NULLABLE	DESCRIPTION
amount	string		Price of the request in string format
currency	string		Currency of the price

note

Currently we only support USD as currency. Currency amounts are represented as strings with two decimal precision, e.g. "34.95".

TurnaroundTime

PROPERTY	TYPE	NULLABLE	DESCRIPTION
upper_bound	string		The estimated upper bound in hours
best_estimate	string		The best estimate of turnaround time in hours
lower_bound	string		The estimated lower bound in hours

We use data from thousands of verification requests to estimate the duration between creation and completion of a request. For a provided company, upper_bound and lower_bound are the time estimates (in hours) that this particular request will take to be fully processed by Truework.

Document

PROPERTY	TYPE	NULLABLE	DESCRIPTION
filename	string		Name of the file e.g. "authorization.pdf"

Enumerations

State

The state helps convey where the verification request is in the Truework process. It will be returned in the JSON objects returned from this endpoint.

The initial state of all verifications is pending-approval, and will switch to processing once Truework begins to process the request. However, it may switch back to pending-approval if it is pending approval by the target.

The states completed, canceled, invalid are all terminal states of a Verification. A Report is only available when it is in the completed state. A Verification will enter the state canceled when either Truework or an API user cancels the request. The invalid state indicates that there are issues with the data e.g. we could not locate the employee at a given employer, or could not find the employer itself.

VALUE	DESCRIPTION
pending-approval	The initial state after creation; the Truework team has not started working on this request yet
action-required	A user action is required to continue processing this request; visit the dashboard for more information
invalid	Contains invalid information that prevents the verification request from being processed by Truework
processing	The Truework team is currently working on the verification request
completed	The verification request has been completed and a report can be found from the reports endpoint
canceled	Truework denied processing of the request or the verifier no longer wants the request to be processed

PermissiblePurpose

A valid purpose is required for Truework to process the verification request. Throughout the API, this is signified by the permissible_purpose field.

VALUE	DESCRIPTION
child-support	Determine child support payments (available to verifiers that represent a state or local child support enforcement agencies)
credit-application	The target's application for credit
employee-eligibility	Employee's eligibility for a benefit granted by a governmental agency required by law to consider the employee's financial responsibility or status
employee-request	The target has issued the verifier written instruction to obtain this information
employee-review-or-collection	Performing a review or collection of the target's account
employment	Employment purposes where the target has given prior written consent
insurance-underwriting-application	Underwriting insurance in response to the target's application
legitimate-reason-initiated	Legitimate business need for the information in connection with a business transaction initiated by the target
legitimate-reason-review	Legitimate business need to review the target's account to determine whether the employee continues to meet the terms of the account
risk-assessment	To assess the credit or prepayment risks associated with an existing credit obligation of the target
subpoena	For a court order or a federal grand jury subpoena

Type

The verification request type is determined by how much information the verifier wants about the target. Throughout the API, this is signified by the type field.

VALUE	DESCRIPTION
employment	A verification of employment
employment-income	A verification of income

UseCase

The verification request use case describes the type of product the verification request is originating from.

VALUE	DESCRIPTION
mortgage	Verification for a mortgage
background	Verification for a background check
tenant	Verification for a rental property
government	Verification for government/social services
auto	Verification for auto lending
lending	Verification for personal loans or consumer lending
credit	Verification for credit cards
identity	Verification for identity or fraud
insurance	Verification for insurance
health	Verification for health services
offers	Verification for offers
account-management	Verification for account management
preapproval	Verification for preapprovals
other	Verification for other products. This exists for historical compatibility, no new verifications can be created with this value