Skip to main content

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#

PROPERTYTYPENULLABLEDESCRIPTION
idstringThe id of the verification request
createdstringCreation date of verification request in ISO 8601 format
typeTypeType of verification report
permissible_purposePermissiblePurposeReason for why this verification is being conducted
stateStateState of the verification request
targetTargetInformation about the verification request target
pricePriceBilling information about how much the verification request will cost once completed
turnaround_timeTurnaroundTimeExpected turnaround time in hours for the verification request; will be an empty if an estimate does not exist for the verification request
use_caseUseCaseUse case for this request
date_of_completionstringThe date when this verification was completed in ISO 8601 format
loan_idstringThe loan_id associated with the verification request
cancellation_reasonstringThe reason for the cancellation of the request; only present when state is canceled
cancellation_detailsstringThe details for the cancellation; only present when state is canceled and available
documentsDocument[]Supporting documentation files provided by the verifier for the verification
reportsReport[]Applicable reports belonging to this request, if the request has been completed
metadataJSONA single level key-value JSON object that can be used to store custom data on the verification request; keys and values must be strings

Target#

PROPERTYTYPENULLABLEDESCRIPTION
first_namestringFirst name of the target
last_namestringLast name of the target
social_security_numberstringThe target's social security number in format ***-**-XXXX
companyCompanyDetails about the target's company
contact_emailstringTarget's email address
date_of_birthstringTarget's date of birth in format YYYY-MM-DD

Company#

PROPERTYTYPENULLABLEDESCRIPTION
namestringThe name of the company
idstringThe id returned in a company search response
phone_numberstringContact phone number for this company
addressstringStreet address of the company
citystringCity of the company
statestringState of the company
zip_codestringZip code of the company

Price#

PROPERTYTYPENULLABLEDESCRIPTION
amountstringPrice of the request in string format
currencystringCurrency 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#

PROPERTYTYPENULLABLEDESCRIPTION
upper_boundstringThe estimated upper bound in hours
best_estimatestringThe best estimate of turnaround time in hours
lower_boundstringThe 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#

PROPERTYTYPENULLABLEDESCRIPTION
filenamestringName 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.

VALUEDESCRIPTION
pending-approvalThe initial state after creation; the Truework team has not started working on this request yet
action-requiredA user action is required to continue processing this request; visit the dashboard for more information
invalidContains invalid information that prevents the verification request from being processed by Truework
processingThe Truework team is currently working on the verification request
completedThe verification request has been completed and a report can be found from the reports endpoint
canceledTruework 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.

VALUEDESCRIPTION
child-supportDetermine child support payments (available to verifiers that represent a state or local child support enforcement agencies)
credit-applicationThe target's application for credit
employee-eligibilityEmployee's eligibility for a benefit granted by a governmental agency required by law to consider the employee's financial responsibility or status
employee-requestThe target has issued the verifier written instruction to obtain this information
employee-review-or-collectionPerforming a review or collection of the target's account
employmentEmployment purposes where the target has given prior written consent
insurance-underwriting-applicationUnderwriting insurance in response to the target's application
legitimate-reason-initiatedLegitimate business need for the information in connection with a business transaction initiated by the target
legitimate-reason-reviewLegitimate business need to review the target's account to determine whether the employee continues to meet the terms of the account
risk-assessmentTo assess the credit or prepayment risks associated with an existing credit obligation of the target
subpoenaFor 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.

VALUEDESCRIPTION
employmentA verification of employment
employment-incomeA verification of income

UseCase#

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

VALUEDESCRIPTION
mortgageVerification for a mortgage
backgroundVerification for a background check
tenantVerification for a rental property
governmentVerification for government/social services
autoVerification for auto lending
lendingVerification for personal loans or consumer lending
creditVerification for credit cards
identityVerification for identity or fraud
insuranceVerification for insurance
healthVerification for health services
offersVerification for offers
account-managementVerification for account management
preapprovalVerification for preapprovals
otherVerification for other products. This exists for historical compatibility, no new verifications can be created with this value