The Orders object

An Order is the starting point for every verification. When you create an Order, Truv automatically creates a User, generates a Bridge Token, and produces a personalized landing page for the user to connect their account. The following diagram illustrates the Order lifecycle.

Orders handle everything to get started: creating an Order is all you need to initiate a verification. The Order creates the User, generates the Bridge Token, and tracks the entire lifecycle from creation to completion.

What happens when you create an Order

User is created automatically from the provided applicant details
Bridge Token is generated for the Order
Landing page is created with a unique share_url for the user
Invite is sent (optional) via email, SMS, or both, or you can share the share_url directly
User connects through Truv Bridge on the landing page
Data is retrieved and the Order status updates as Tasks complete

Order lifecycle and webhooks

Orders are asynchronous. The typical flow is:

You create an Order via the API or Dashboard.
The user authenticates with one or more employers through Truv Bridge.
Truv retrieves the data and fires a task-status-updated webhook for each employer/account as it completes.
Truv fires an order-status-updated webhook each time a suborder — an employer or financial account — changes status, for example as each connection resolves.
You retrieve the verification data from the Retrieve an order endpoint.
Truv fires an order-finalized webhook once the order reaches its terminal state — no further data collection or refresh occurs.

Webhook	Scope	Use for
`task-status-updated`	Per employer/account connection	Monitoring individual connection progress, processing data as it arrives
`order-status-updated`	Per suborder (employer/financial account)	Suborder progress; fires on status changes, not on login attempts
`order-finalized`	Entire order group	Knowing the order is permanently final, with no further data collection or refresh

In a multi-employer order, task-status-updated fires for every connection attempt, including failed logins. order-status-updated fires whenever a suborder — an employer or financial account — changes status, but not on individual login attempts. Use task-status-updated for fine-grained, real-time progress; use order-status-updated to track suborder status changes.

The no_data status means the user successfully connected to the provider, but the provider returned zero records. This is distinct from an error status, which indicates a connection failure. A no_data result typically means the provider has no history for the applicant, not that the connection failed.

Create orders

Create Orders through the Truv Dashboard or programmatically via the Create an Order endpoint. Orders are customizable for these components:

Landing page
Text message (optional)
Email (optional)

Attributes

The attributes of Orders are below.

Report limits: A single VOIE order supports a maximum of 5 employers, and a single VOA order supports a maximum of 5 financial institutions. If you need to verify more, create additional orders for the same user.

Attribute	Type	Description
id	string	Unique ID of order
products	array	List of products selected for Order
source	string	Type of platform: `floify`, `besmartee`, `lenderlogix`, `encompass_consumer_connect`, `byte`, `core_logic`, `xactus`, `constellation`, `banno`, `mx`, `q2`, `clutch`, `accio`, `encompass`, `tpo_connect`, `darkmatter`, `tazworks`, `internal`, `simplenexus`, `alkami`, `blue_sage`, `lodasoft`, `blend`, `tidalwave`, `external_webpage`
order_number	string	External ID from client
custom_field	string	Client-provided custom field for use in email, SMS, or landing page. NOTE: Enable this field in the dashboard customization section.
client_name	string	Client name displayed on the order page
first_name	string	First name
last_name	string	Last name
user_id	string	Unique ID of user
bridge_token	string	UUID value of bridge token for the Order
share_url	string	Landing page URL to share
short_share_url	string	Shortened verification URL to share
created_at	string	ISO 8601 value for when Order was created
updated_at	string	ISO 8601 value for when Order was last updated
completed_at	string	ISO 8601 value for when Order was successfully completed
canceled_at	string	ISO 8601 value for when Order was canceled
expired_at	string	ISO 8601 value for Order expiration
is_expired	boolean	Status of Order expiration
user_consent_at	string, null	ISO 8601 time when the user first gave consent.
initial_order	string	ID of origin Order, from Order data refresh action
refresh_order	string	ID of last refresh Order created by Order data refresh action
employers	array of objects	List of user employers, see Employers object
insurance	object	Insurance verification metadata, see Insurance object
financial_accounts	array of objects	Financial accounts metadata, see Financial accounts object
manager	object	Associated Order manager info, see Manager object
loan	object	Loan information, see Loan object
cc_emails	array of strings	Email addresses for CC on order status updates (max 15)
notes	string	Free text field for notes (max 2000 characters)
template_id	string	ID of template
voie_report_id	string	Income and employment verification report ID (accepted by Fannie Mae DU and Freddie Mac LPA)
voa_report_id	string	Asset verification report ID
income_insights_report_id	string	Income Insights report ID
aim_check_report_id	string	AIM check report ID for income calculation based on uploaded documents

To get a PDF version of the report please use the corresponding report_id along with the GET endpoint in the User Reports section.

voie_report_id auto-population: The voie_report_id field is only populated automatically when an account-level setting is enabled. This setting generates a Fannie Mae DU / Freddie Mac LPA compatible report ID upon order completion. Contact Truv support to enable this feature for your account.

Company address object

The values in this table are for the address object of the company.

Attribute	Type	Description
street	string	Street
city	string	City
state	string	State
zip	string	Zip
country	string	Country

Employers object

View information for employer object field data below.

Attribute	Type	Description
id	string	Unique ID
product_type	string	Type of product, see values below: `income`, `employment`, `deposit_switch`, `pll`
status	string	Order status, see values below: `pending`, `sent`, `completed`, `error`, `canceled`, `expired`, `no_data`, `skipped`
suborder_number	string	External ID
created_at	string	Date and time when Order was created
bridge_token	string	UUID value of bridge_token
link_id	string	Link ID for connected account
access_token	string, null	Access token to perform data refresh
pdf_report	uri, null	Verification report in PDF format
data_source	string	Source of data, see values below: `payroll` - Payroll provider parsing, `docs` - User uploaded documents, `insurance` - Insurance data, `financial_accounts` - Bank data, `tax` - Tax documents, `scoring_attributes` - Transactions scoring attributes report
provider	object	see Provider object
is_suspicious	boolean	Status of data from source marked as suspicious, such as if detecting fraud in uploaded documents or user SSN does not match data
start_date	string	Employment start date
end_date	string	Employment end date
company_name	string	Company name
company_address	object	Company address, see Company address object
company_logo	uri	Company logo URL
company_domain	string	Company website domain
employments	array of objects	List of employments, see Employments object

Provider object

This table contains data for the provider object.

Attribute	Type	Description
id	string	Provider unique ID
name	string	Provider name
logo_url	uri	Provider logo URL

Employments object

The Employments object contains the values and descriptions below.

Attribute	Type	Description
income	string	Income amount not including commission or bonuses, only for income product. Null for employment product
income_unit	string	Pay interval for income field, only for income product. `YEARLY` - Annual income, `MONTHLY` - Monthly income, `WEEKLY` - Weekly income, `DAILY` - Daily income, `HOURLY` - Hourly income. Null for employment product
pay_rate	string	Payment rate per pay cycle, only for income product. Null for employment product
pay_frequency	string	Pay frequency, only for income product. `M` - Monthly, `SM` - Semi-Monthly, `W` - Weekly, `BW` - Bi-Weekly, `A` - Annually, `SA` - Semiannually, `C` - Commission. Null for employment product
statements	array of objects	List of Paystubs received from a payroll provider, only for income product, see Statements object. Null for employment product
annual_income_summary	array of objects	Annual income summary by years, only for income product, see Annual income summary object. Null for employment product
bank_accounts	array of objects	List of bank accounts linked to employment, only for income product, see Bank accounts object. Null for employment product
w2s	array of objects	List of W-2 forms linked to employment, only for income product, see W2s object. Null for employment product
id	string	Unique ID
is_active	boolean	Status of active employment
job_title	string	Employee’s job title
job_type	string	Employee’s job type. `F` - Full Time, `P` - Part Time, `S` - Seasonal, `D` - Daily (per diem), `C` - Contract
start_date	date	Employee’s hire date
original_hire_date	date	Original hire date
end_date	date	Employee’s end date
external_last_updated	date	Indicates date of last updated employment data from Payroll Provider
derived_fields	array of strings	Array of derived fields
missing_data_fields	array of strings	List of missing data fields from payroll response
manager_name	string, null	Supervisor’s name
profile	object	Person’s identity information
company	object	Company object
gse_accepted	boolean	Status of provider eligibility from Fannie Mae Desktop Underwriter

Statements object

View the table below for information from the Statements object.

Attribute	Type	Description
id	string	Unique ID
check_number	string	External ID of pay stub from payroll provider
pay_date	date	Pay date
net_pay	string	Net pay
net_pay_ytd	string	Net pay year to date
gross_pay	string	Gross pay
gross_pay_ytd	string	Gross pay year to date
bonus	string	Bonus
commission	string	Commission
hours	string	Work hours during pay period
basis_of_pay	string	Basis of pay. `S` - Salary, `H` - Hourly, `D` - Daily, `W` - Weekly, `M` - Monthly
period_start	date	Period start
period_end	date	Period end
regular	string	Regular pay
regular_ytd	string	Regular salary year to date
other_pay_ytd	string	All other payment year to date
bonus_ytd	string	Bonus year to date
commission_ytd	string	Commission year to date
overtime	string	Overtime pay
overtime_ytd	string	Overtime pay year to date
other_pay	string	All other payment
earnings	array of objects	Earnings for this pay cycle by type
earnings_ytd	array of objects	Earnings year to date by type
deductions	array of objects	Deductions for pay cycle by type
deductions_ytd	array of objects	Deductions year to date by type
md5sum	string	MD5 hash value computed based on file content
file	uri	Link to pay stub file, format is specified in the content-type
derived_fields	array of strings	Array of derived fields
missing_data_fields	array of strings	List of missing data fields from payroll response

Annual income summary object

Find information for the attributes and values of the annual income summary object.

Attribute	Type	Description
id	string	Unique ID
year	integer	Income report year
regular	string	Regular salary
bonus	string	Bonus
commission	string	Commission
overtime	string	Overtime pay
other_pay	string	All other payment forms
net_pay	string	Net pay
gross_pay	string	Gross pay

Bank accounts object

The table below covers the attributes within the bank accounts object.

Attribute	Type	Description
account_number	string	Account number
routing_number	string	Routing number
account_name	string	User friendly account name
account_type	string	Account type. `C` - Checking account, `S` - Savings account
deposit_type	string	Deposit type. `E` - Entire paycheck, `P` - Percentage of the paycheck, `A` - Fixed amount from the paycheck
deposit_value	string	Deposit value
bank_name	string	Bank name

W2s object

The values in this table are for the W-2s object field.

Attribute	Type	Description
file	uri	Link to W2 report file, format is specified in the content-type
md5sum	string	MD5 hash value computed based on file content
year	integer	Year
wages	string	Wages, tips, other compensation (Section 1)
federal_tax	string	Federal income tax withheld (Section 2)
social_security_wages	string	Social security wages (Section 3)
social_security_tax	string	Social security tax withheld (Section 4)
medicare_wages	string	Medicare wages (Section 5)
medicare_tax	string	Medicare tax withheld (Section 6)
gross_pay	string	Gross pay

Company object

This table covers values within the company object.

Attribute	Type	Description
name	string	Company name
address	object	Address object
phone	string	Company phone number
ein	string	Employer Identification Number

Address object

The values in this table are for the address object of the company.

Attribute	Type	Description
street	string	Street
city	string	City
state	string	State
zip	string	Zip
country	string	Country

Insurance object

This table’s values contain information for the insurance object.

Attribute	Type	Description
id	string	Unique ID
product_type	string	Type of product
status	string	Order status
suborder_number	string	External ID
created_at	string	Date and time when Order was created
bridge_token	string	UUID value of bridge_token
link_id	string	Link ID for connected account
access_token	string, null	Access token to perform data refresh
pdf_report	uri, null	Verification report file as a PDF
data_source	string	Source of data, see values below: `payroll` - Payroll provider parsing, `docs` - User uploaded documents, `insurance` - Insurance data, `financial_accounts` - Bank data, `tax` - Tax documents, `scoring_attributes` - Transactions scoring attributes report
provider	object	see Provider object
is_suspicious	boolean	Status of data from source marked as suspicious, such as if detecting fraud in uploaded documents or user SSN does not match data
provider_id	string	Pre-selected ID of insurance provider

Financial accounts object

The financial accounts object attributes below have type information and descriptions.

Attribute	Type	Description
id	string	Unique ID
product_type	string	Type of product
status	string	Order status
suborder_number	string	External ID
created_at	string	Date and time when Order was created
bridge_token	string	UUID value of bridge_token
link_id	string	Link ID for connected account
access_token	string, null	Access token to perform data refresh
pdf_report	uri, null	Verification report file as a PDF
data_source	string	Source of data, see values below: `payroll` - Payroll provider parsing, `docs` - User uploaded documents, `insurance` - Insurance data, `financial_accounts` - Bank data, `tax` - Tax documents, `scoring_attributes` - Transactions scoring attributes report
provider	object	see Provider object
is_suspicious	boolean	Status of data from source marked as suspicious, such as if detecting fraud in uploaded documents or user SSN does not match data
accounts	array of objects	List of connected accounts, see Accounts object

Accounts object

Attribute	Type	Description
id	string	Unique identifier of account
type	string	Parent type of account, e.g. `CHECKING` or `SAVINGS`
subtype	string	Account subtype, e.g. `MONEY_MARKET`, `HOME_EQUITY`
mask	string	Last 4 digits of the account number

Manager object

The manager object attributes below have information on type and description.

Attribute	Type	Description
email	string	Email of Order manager
name	string	Name of Order manager

Loan object

View the table below for type and description of the attributes in the loan object.

Attribute	Type	Description
loan_number	string	Loan identifier
external_id	string	External loan ID (e.g. from POS)
originator_name	string	Name of loan originator
originator_email	string	Email of loan originator
loan_processor_name	string	Name of the loan processor
loan_processor_email	string	Email of the loan processor

Endpoints

The list below are the available endpoints for Orders.

Example response

The JSON object below is a sample response.

{
  "id": "39aa1486ccca4bc19cda071ffc1ba392",
  "products": [
    "income"
  ],
  "source": "floify",
  "order_number": "1534332",
  "custom_field": "string",
  "client_name": "Unnamed Verifications Inc.",
  "first_name": "John",
  "last_name": "Doe",
  "user_id": "99dd17074ac94aa9ace2621d657c7610",
  "bridge_token": "e4100fccdae94691b4414c7306220c06",
  "share_url": "https://cdn.truv.com/employment.html?bridge_token=63b4af88facb40e48f517c1e8c7abdf4&order_group_id=39aa1486ccca4bc19cda071ffc1ba392",
  "short_share_url": "https://truv.com/s/BIlEyh1A",
  "created_at": "2021-04-21T21:45:14.418542Z",
  "updated_at": "2021-04-21T21:45:14.418542Z",
  "canceled_at": "2021-04-22T21:45:14.418542Z",
  "completed_at": "2021-04-22T21:45:14.418542Z",
  "expired_at": "2021-04-24T21:45:14.418542Z",
  "is_expired": true,
  "user_consent_at": "2021-04-21T21:45:14.418542Z",
  "initial_order": "f5dc0239e2094dbc90ab2edc1918a9df",
  "refresh_order": "9b96606355b94e8abff8ed8d75aa2027",
  "employers": [
    {
      "id": "ad9f14440d624ec3b0f66e81e44518c7",
      "product_type": "income",
      "status": "pending",
      "suborder_number": "133982343355",
      "created_at": "2021-04-21T22:12:59.346109Z",
      "bridge_token": "e4100fccdae94691b4414c7306220c06",
      "link_id": "e4100fccdae94691b4414c7306220c06",
      "access_token": "e4100fccdae94691b4414c7306220c06",
      "pdf_report": "https://cdn.truv.com/report.pdf",
      "data_source": "payroll",
      "provider": {
        "id": "truv_api",
        "name": "Sandbox Provider",
        "logo_url": "https://cdn.truv.com/providers/truv-blue.svg"
      },
      "is_suspicious": true,
      "start_date": "2019-08-24",
      "end_date": "2019-11-27",
      "company_name": "Facebook Demo",
      "company_address": {
        "street": "1 Hacker Way",
        "city": "Menlo Park",
        "state": "CA",
        "zip": "94025"
      },
      "company_logo": "https://cdn.truv.com/logos/facebook.svg",
      "company_domain": "facebook.com",
      "employments": [
        {
          "income": "70000.00",
          "income_unit": "YEARLY",
          "pay_rate": "6500.00",
          "pay_frequency": "M",
          "statements": [
            {
              "id": "24d7e80942ce4ad58a93f70ce4115f5c",
              "check_number": "29205182",
              "pay_date": "2018-05-15",
              "net_pay": "11500.32",
              "net_pay_ytd": "31980.64",
              "gross_pay": "13900.11",
              "gross_pay_ytd": "49200.00",
              "bonus": "100.00",
              "commission": "12000.00",
              "hours": "40.00",
              "basis_of_pay": "S",
              "period_start": "2018-05-01",
              "period_end": "2018-05-15",
              "regular": "1695.11",
              "regular_ytd": "23000.00",
              "other_pay_ytd": "700.00",
              "bonus_ytd": "1000.00",
              "commission_ytd": "24000.00",
              "overtime": "45.00",
              "overtime_ytd": "500.00",
              "other_pay": "60.00",
              "earnings": [
                {
                  "name": "Regular",
                  "amount": "1935.77",
                  "category": "regular",
                  "rate": null,
                  "units": null
                },
                {
                  "name": "Overtime",
                  "amount": "60.58",
                  "category": "overtime",
                  "rate": "30.29",
                  "units": "2"
                }
              ],
              "earnings_ytd": [
                {
                  "name": "Regular",
                  "amount": "1935.77",
                  "category": "regular",
                  "rate": null,
                  "units": null
                },
                {
                  "name": "Overtime",
                  "amount": "60.58",
                  "category": "overtime",
                  "rate": "30.29",
                  "units": "2"
                }
              ],
              "deductions": [
                {
                  "name": "Social Security Tax",
                  "amount": "127.01",
                  "category": "socialsec"
                },
                {
                  "name": "VA State Income Tax",
                  "amount": "46.23",
                  "category": "state"
                },
                {
                  "name": "Medicare Tax",
                  "amount": "29.7",
                  "category": "medicare"
                }
              ],
              "deductions_ytd": [
                {
                  "name": "Social Security Tax",
                  "amount": "127.01",
                  "category": "socialsec"
                },
                {
                  "name": "VA State Income Tax",
                  "amount": "46.23",
                  "category": "state"
                },
                {
                  "name": "Medicare Tax",
                  "amount": "29.7",
                  "category": "medicare"
                }
              ],
              "md5sum": "03639d6a6624f69a54a88ea90bd25e9d",
              "file": "https://cdn.truv.com/paystub_sample.pdf",
              "derived_fields": [
                "basis_of_pay"
              ],
              "missing_data_fields": [
                "earnings_ytd"
              ]
            }
          ],
          "annual_income_summary": [
            {
              "id": "24d7e80942ce4ad58a93f70ce4115f5c",
              "year": 2018,
              "regular": "23000.00",
              "bonus": "1000.00",
              "commission": "24000.00",
              "overtime": "500.00",
              "other_pay": "700.00",
              "net_pay": "31980.64",
              "gross_pay": "49200.00"
            }
          ],
          "bank_accounts": [
            {
              "account_number": "1234567890",
              "routing_number": "123456789",
              "account_name": "My Bank",
              "account_type": "C",
              "deposit_type": "A",
              "deposit_value": "200.00",
              "bank_name": "TD Bank"
            }
          ],
          "w2s": [
            {
              "file": "https://cdn.truv.com/W2_sample.pdf",
              "md5sum": "f65e30c39124ad707ac4b3aeaee923a7",
              "year": 2020,
              "wages": "900.50",
              "federal_tax": "75.01",
              "social_security_wages": "900.50",
              "social_security_tax": "56.30",
              "medicare_wages": "900.50",
              "medicare_tax": "13.15",
              "gross_pay": "18211.48"
            }
          ],
          "id": "24d7e80942ce4ad58a93f70ce4115f5c",
          "is_active": false,
          "job_title": "PR associate",
          "job_type": "F",
          "start_date": "2018-01-01",
          "original_hire_date": "2017-06-21",
          "end_date": "2025-03-13",
          "external_last_updated": "2025-03-13",
          "dates_from_statements": false,
          "derived_fields": [
            "is_active"
          ],
          "missing_data_fields": [
            "w2s"
          ],
          "manager_name": "Jenny McDouglas",
          "profile": {
            "id": "48427a36d43c4d5aa6324bc06c692456",
            "created_at": "2022-06-07T15:00:00Z",
            "updated_at": "2022-06-31T15:00:00Z",
            "first_name": "John",
            "last_name": "Doe",
            "full_name": "John Doe",
            "middle_initials": "K",
            "email": "john.doe@example.com",
            "ssn": "123456789",
            "date_of_birth": "1992-03-03",
            "home_address": {
              "street": "1 Morgan Ave",
              "city": "Los Angeles",
              "state": "CA",
              "zip": "90210",
              "country": "US"
            }
          },
          "company": {
            "name": "Facebook Demo",
            "address": {
              "street": "1 Morgan Ave",
              "city": "Los Angeles",
              "state": "CA",
              "zip": "90210",
              "country": "US"
            },
            "phone": "6503087300",
            "ein": "12-345678"
          }
        }
      ]
    }
  ],
  "insurance": {
    "id": "ad9f14440d624ec3b0f66e81e44518c7",
    "product_type": "insurance",
    "status": "pending",
    "suborder_number": "133982343355",
    "created_at": "2021-04-21T22:12:59.346109Z",
    "bridge_token": "e4100fccdae94691b4414c7306220c06",
    "link_id": "e4100fccdae94691b4414c7306220c06",
    "access_token": "e4100fccdae94691b4414c7306220c06",
    "pdf_report": "https://cdn.truv.com/report.pdf",
    "data_source": "insurance",
    "provider": {
      "id": "truv_api",
      "name": "Sandbox Provider",
      "logo_url": "https://cdn.truv.com/providers/truv-blue.svg"
    },
    "is_suspicious": true,
    "provider_id": "geico"
  },
  "manager": {
    "email": "john.doe@example.com",
    "name": "John Doe"
  },
  "financial_accounts": [
    {
      "id": "ad9f14440d624ec3b0f66e81e44518c7",
      "product_type": "transactions",
      "status": "pending",
      "suborder_number": "133982343355",
      "created_at": "2021-04-21T22:12:59.346109Z",
      "bridge_token": "e4100fccdae94691b4414c7306220c06",
      "link_id": "e4100fccdae94691b4414c7306220c06",
      "access_token": "e4100fccdae94691b4414c7306220c06",
      "pdf_report": "https://cdn.truv.com/report.pdf",
      "data_source": "financial_accounts",
      "provider": {
        "id": "truv_api",
        "name": "Sandbox Provider",
        "logo_url": "https://cdn.truv.com/providers/truv-blue.svg"
      },
      "is_suspicious": true,
      "accounts": [
        {
          "id": "3aed25abdbc246138b84a2afd46cb05b",
          "type": "CHECKING",
          "subtype": null,
          "mask": "6789"
        }
      ]
    }
  ],
  "loan": {
    "loan_number": "MUUT220700012",
    "originator_name": "John Doe",
    "originator_email": "john@example.com",
    "loan_processor_name": "John Doe",
    "loan_processor_email": "john@doe.com",
    "external_id": "c505e0f1-b413-4fdc-853f-c87e7d2cc4a5"
  },
  "template_id": "9b96606355b94e8abff8ed8d75aa2027",
  "cc_emails": [
    "user@example.com"
  ],
  "notes": "string",
  "voie_report_id": "b19c454a98594b4084b71e3b62873d29",
  "voa_report_id": "b19c454a98594b4084b71e3b62873d29",
  "income_insights_report_id": "b19c454a98594b4084b71e3b62873d29",
  "aim_check_report_id": "FM-1234-39aa1486ccca4bc19cda071ffc1ba392"
}

​What happens when you create an Order

​Order lifecycle and webhooks

​Create orders

​Attributes

​Company address object

​Employers object

​Provider object

​Employments object

​Statements object

​Annual income summary object

​Bank accounts object

​W2s object

​Company object

​Address object

​Insurance object

​Financial accounts object

​Accounts object

​Manager object

​Loan object

​Endpoints

​Example response

What happens when you create an Order

Order lifecycle and webhooks

Create orders

Attributes

Company address object

Employers object

Provider object

Employments object

Statements object

Annual income summary object

Bank accounts object

W2s object

Company object

Address object

Insurance object

Financial accounts object

Accounts object

Manager object

Loan object

Endpoints

Example response