Loan Origination System (LOS)
Integrate your Loan Origination system with Truv's Verification of Income and Employment (VOIE) solution.
Overview
The Order is a custom landing page for your users. Users connect their accounts to their providers when they use Orders. Send personalized invitations to your users through email or phone. Orders are a simple process for contacting your borrowers for next steps.
Positioning of the Truv Order
To integrate Truv's Order functionality, it is recommended to use the existing verification flow while adding Truv as the provider to trigger the verification. This approach minimizes change management for loan processors, thereby enhancing the user experience and reducing friction.
Integration Process
Create an Order
Call /orders/
to create a new order with the following parameters:
- Required fields
products
: Insert the product(s) desired. For income specify["income"]
, and add additional products to the list, if any.first_name
&last_name
: Enter the first and last name of the borroweremail
and/orphone
: Enter either email and/or mobile phone number for Truv to send the Truv notification to the borrower. If you leave this section blank, you would need to retrieve the Truv verification link from the JSON response under"share_url"
.Note
Truv will not be able to send any notifications if both email and phone number are left blank.
- Recommended fields
loan
: The loan object has several fields that allow to identify the loan.loan_number
: The loan number identifying the loanoriginator_name
: The first and last name of the loan originatororiginator_email
: The email of the loan originatorloan_processor_name
: The first and last name of the loan processorloan_processor_email
: The email of the loan processor
ssn
: Borrower's social security number. Should be either 4 or 9 digits in length. Truv compares the SSN entered against the one provided by the payroll system and returns aconfig_error
if there is a mismatch.manager
: The manager object identifies the Truv Order creatoremail
: The email of the Order creatorname
: The first and last name of the Order creator
Note
Truv will send a notification to the provided email address(es) when the Truv Order is created as well as when they are completed/expired/cancelled.
- Optional fields
employers
: The employers object allows you to enter the employment information for the borrower to verify. Truv supports up to 5 employers per single Truv Order.start_date
: The start date of employmentcompany_name
: The name of the employer
data_sources
: Specify["payroll"]
to connect exclusively to payroll. To enable fallback options, include additionaldata_sources
such as"docs"
and/or"financial_accounts"
in the list.template_id
: Call/templates/
to list all custom templates created by the lender. And allow them to select the desired template into the Order.
Tip
Ensure the
order_id
is visible to the lender as it serves as an identifier to contact the Truv Support staff.
Retrieve an Order
Call /orders/{id}/
to fetch the details of a completed order. This ensures access to the latest order information. The employers
object contains, but is not limited to, the following information:
status
: The status of the Orderpdf_report
: A URL to the employer-specific PDF reportemployments
: The employments object provides income information for each verified employment. It also includes a"file"
field within thestatements
andw2s
objects, which allows retrieval of the corresponding income documents.voie_report_id
: Thereport_id
must be passed to the corresponding government-sponsored enterprise (GSE) - Fannie Mae’s DU Validation Service and Freddie Mac's AIM. More information here.
Please review Truv’s Data Reference for Income and Employment documentation, which includes JSON responses and document samples, including Truv’s Income and Employment PDF Report.
Note
The
data_source
field indicates whether the borrower directly connected to the payroll system ("payroll"
) or used an alternate fallback such as manual document upload ("doc_upload"
).
Refresh Order Data
Call /orders/{id}/
with the original order_id
to trigger a re-verification. This allows the order data to be refreshed and kept up-to-date.
Truv recommends allowing the lender to choose the product type and employers for re-verification prior to triggering the Order Refresh:
products
: Enter["employment"]
or["income"]
to the data refresh order endpoint. Most re-verifications requireemployment
only.employers
: The employer ID to be refreshed. The employer ID is located in the original JSON response when retrieving the successful Truv Orderinclude_recent_paystub
: Set totrue
to refresh employment-only data and include the most recent paystub.
Tip
Truv recommends having the lender select the options for re-verification, as shown in the image below.
Update an Order
Call /orders/{id}/
to update of a Truv Order. This endpoint allows to modify the first or last name, or the SSN (Social Security Number) of the order. This action is only available while the Truv Order is pending.
Cancel an Order
Call /orders/{id}/cancel/
to cancel a pending Truv Order. If the order is partially completed, completed verification data can be retrieved using the Retrieve an Order endpoint. Once canceled, the order cannot be reopened by the borrower.
Webhooks
Listen for the order-status-updated
webhooks, which provide the status of the Truv Order and indicate when the data is ready to be retrieved once the status
is set to completed
. The data_source
specifies the income source of the Order. Use the order_id
, user_id
, and link_id
to trigger the corresponding income information retrieval. More info here.
Webhook Setup
Subscribe to Truv webhooks by navigating to the Webhooks section of the dashboard and entering the URL endpoint for receiving updates.
Order status
The bullet points below cover the user’s Order status.
- pending - Truv is processing the borrower's information
- sent - Order email or SMS is on its way to borrower
- completed - Borrower has completed request for action
- error - Notification issue
- canceled - Order is no longer requested
- expired - Order is past expiration date, no longer valid
- skipped - Borrower has exited Order before completing request for action
- no data - Provider has no data
Testing
Income can be tested in Sandbox using Truv's Testing credentials. Here are some login examples:
- Happy path: username:
goodlogin
, password:goodpassword
, SSN:991-91-9991
- Multiple employers: username:
multiple.employments
, password:goodpassword
Best Practices
Customization
Personalize the text users receive via email and SMS. Customizations are available for landing pages. Use the Customization templates in the Truv dashboard or the Create a customization template endpoint for additional options.
Notifications
Order links are available within the dashboard or through the API for integration with notification systems.
Tip
Combining email and SMS messaging improves order success rates from opening to completion. High-intent borrowers complete over 50% of verifications within 2 hours.
Reminders
The default reminder setting is 72 hours, with three reminders sent at equal intervals. For example, if the link expiration is 72 hours, reminders are sent every 24 hours. If the link expiration period is different, the reminder intervals adjust accordingly to ensure three reminders are sent. Customize expiration times and reminder schedules within the dashboard.
Updated 24 days ago