Overview

Embedded Orders provide a streamlined way to integrate income and employment verification into your custom Point-of-Sale system. This approach combines the benefits of Truv's verification capabilities with simplified order management, allowing users to connect multiple accounts and generate comprehensive reports. Embedded orders handle employer search, credentials, multi-factor authentication, and error handling within a unified workflow.

Positioning Embedded Orders

Truv recommends positioning embedded orders at the employment level of the loan application. This approach is a superior way to verify income and employment and should always be offered as a primary alternative to manual document upload.

There are two ways to position embedded orders:

i. The borrower searches for employers within the order interface (recommended)

1. Instead of letting the borrower enter employment information manually, add a "Verify instantly" button.
2. When the borrower clicks the button, the embedded order interface opens and the borrower can search for and connect to multiple employers within a single session.
3. The borrower can add multiple employers as needed, all tracked within the same order.

ii. The borrower enters employer information prior to launching the order

1. When the borrower enters employer information, use the Search companies API endpoint to let the borrower select the appropriate company.
2. Once employers are selected, create an order and launch the embedded interface with pre-populated employer information.
3. The borrower can still add additional employers within the order interface as needed.

📘

Tip

Truv recommends letting the borrower try to verify their income and employment information through embedded orders. If the verification flow fails for any reason, you can then let the borrower go through an alternate fallback.

Embedding Orders

Please refer to Truv's embedded orders documentation for step-by-step implementation guidance. Key implementation considerations:

1. Create an Order

Start by creating an order using the Orders API. Include the borrower's information and specify the products you need:

curl --request POST \
     --url https://prod.truv.com/v1/orders/ \
     --header 'X-Access-Client-Id: {{client_id}}' \
     --header 'X-Access-Secret: {{access_key}}' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "first_name": "John",
  "last_name": "Doe",
  "ssn": "991919991",
  "products": ["income"]
}
'

2. Initialize the Embedded Order

Use the bridge_token from the order response to initialize the embedded interface:

<script src="https://cdn.truv.com/bridge.js"></script>
<script>
  const bridge = TruvBridge.init({
    isOrder: true,
    bridgeToken: bridgeToken,
    onLoad() {},
    onEvent(type, payload, source) {},
    onClose() {},
    onSuccess() {}
   })
</script>

3. Product Configuration

When creating orders, you can specify multiple products:

• income: Income and employment verification from payroll systems
• financial_accounts: Bank account transactions and assets
• docs: Document upload capability for paystubs and W2s
• tax: Tax return verification through IRS connections
• insurance: Insurance verification (recommended for loan servicers)

📘

Note

• Multiple employers can be connected within a single order, eliminating the need for separate tokens.
• Each borrower requires their own unique order with their corresponding personal information.

Tracking successful and unsuccessful verifications

There are two ways to track the status of verifications through embedded orders:

1. Order Interface Callbacks: The embedded order interface provides callbacks to track user interactions:

   • onSuccess(): Triggered when the user successfully completes all verifications and clicks "I'm done"
   • onEvent(type, payload, source): Receives events from both the order page and individual connection widgets
   • onClose(): Triggered when the user closes the order interface

2. Webhooks: Monitor order progress through webhook events:

   • task-status-updated: Tracks individual connection attempts and status changes
   • order-status-updated: Tracks overall order completion status

A successful order is fully completed when the order status is set to completed and all required verifications have a task status of Done.

Retrieving information after successful verification

When an order is completed successfully, you can retrieve all verification data using the Retrieve an Order API endpoint with the order_id. This single request provides:

• Data from all connected employers and accounts
• A user-level VOIE report ID that is GSE-approved (Fannie Mae and Freddie Mac)
• Individual access_token and link_id values for each connection
• Comprehensive employment, income, and other verification data

The order response contains all verification data in a single, structured format, eliminating the need for multiple API calls or token exchanges.

📘

Tip

Truv recommends taking the information from the JSON response and populating it in your POS system. 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.

This will simplify the process for the borrower as they would not need to fill out the income and employment information and the information would come directly from the source. Moreover, the lender will have access to the required income and employment information coming directly from the borrower’s payroll system.

Employment data refresh/re-verification

The lender may require a re-verification of employment confirming borrower's active employment. For orders, use the Create a Data Refresh Order API endpoint with the original order_id.

Truv recommends letting the lender choose the product type for re-verification as shown in the image below. Depending on the selection, the corresponding product_type (employment or income) is selected in the refresh order API endpoint. Most re-verifications require employment only.

📘

Note

If the original order was employment only, then re-verifications cannot include income.

The status of the refresh order can be tracked via order-status-updated webhooks or by retrieving the refreshed order data using the Retrieve an Order API endpoint. Successful refreshes will generate an updated report accessible within your system.

📘

Note

If the refresh order is unsuccessful, Truv will automatically send a new notification to the borrower requesting them to go through the verification process again.

Adding Orders to Tasks

If the verification process was not successful during the loan application process, embedded orders can be added to Tasks in your POS system. Some lenders prefer to have the option to display the verification experience at the application level and/or at the Task level after the loan application is submitted.

There are two ways to implement orders in Tasks:

1. Embedded Orders: Within the POS system, under Tasks, the borrower clicks on the "Verify instantly" button. This creates and loads an embedded order interface where the borrower can connect to multiple employers within a single session, eliminating the need for separate verification flows.

2. Shared Order Links: When adding verification to Tasks, create an order using the Orders API and use the generated share_url to send a verification link to the borrower via email and/or text message. This allows verification without requiring the borrower to log into the POS system. The notification flow can be customized using Truv's Custom Templates.

   • When verification is complete, lenders can receive email notifications and track status using order-status-updated webhooks
   • Completed verification data can be retrieved using the Retrieve an Order API endpoint with the order_id

📘

Note

Order refresh/re-verification uses the Create a Data Refresh Order API endpoint with the original order_id. If the refresh fails, Truv automatically sends a new notification to the borrower requesting them to complete the verification process again.

Testing

Truv provides Testing Credentials to test for different scenarios by using the Sandbox API keys that can be retrieved from the API keys section of the Truv Dashboard. The Sandbox environment does not connect to real payroll providers but is designed to test the implementation with various use cases. When testing for failed Refreshes/Re-verifications, please use the MFA password for the original verification. Webhooks can be configured in the Truv Dashboard under Webhooks and can be separated between Sandbox and Production environments.