Overview

An Order is a personal landing page created for a user to connect their account. These are personalized invites sent to a user's email or phone number. Create Orders with the Truv Dashboard or programmatically using API endpoints.

Orders are customizable for these three components.

Landing page
Text message
Email

Invite users to their personalized landing pages using text message, email, or both. Users proceed to a personalized landing page when clicking on an invite link.

Attributes

The attributes of Orders are below.

Attribute	Type	Description
id	string	Unique ID of order
products	array	List of products selected for Order
source	string	Type of platform, `internal`, `accio`, `tazworks`, `encompass`, `simplenexus`, `external_webpage`
order_number	string	External ID from client
loan_number	string	~~Loan identifier~~(Deprecated, use Loan object field for loan details).
company_name	string	Prospective employer name
company_address	array of objects	Prospective employer address, see Company address object
company_domain	string	Prospective employer website domain
custom_field	string	Client-provided custom field, can be used in email, SMS, or landing page NOTE: This field is only available when enabled in the dashboard customization section.
client_name	string	Verification agency name
first_name	string	First name
last_name	string	Last name
user_id	string	Unique ID of user
share_url	string	Landing page 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
canceled_at	string	ISO 8601 value for when Order was canceled
expired_at	string	ISO 8601 value for Order expiration
is_expired	bool	Status of Order expiration
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	array of objects	Insurance verification metadata, see Insurance object
bank	array of objects	Bank transactions metadata, see Bank object
manager	array of objects	Associated Order manager info, see Manager object
loan	array of objects	Loan information, see Loan object
template_id	string	ID of template
fannie_voie_report_id	string	Fannie Mae income and employment verification report ID

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	Access token to perform data refresh
pdf_report	uri	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	array of objects	Payroll or insurance provider, 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	array of objects	Company address, see Company address object
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_update	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	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
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	Access token to perform data refresh
pdf_report	uri	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	array of objects	Payroll or insurance provider, 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

Bank object

The bank 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	Access token to perform data refresh
pdf_report	uri	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	array of objects	Payroll or insurance provider, 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

Manager object

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

Attribute	Type	Description
email	string	Email or 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
originator_name	string	Name of loan originator
originator_email	string	Email of loan originator

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": "accio",
  "order_number": "1534332",
  "loan_number": "MUUT220700012",
  "company_name": "Facebook Demo",
  "company_address": {
    "street": "1 Hacker Way",
    "city": "Menlo Park",
    "state": "CA",
    "zip": "94025"
  },
  "company_domain": "facebook.com",
  "custom_field": "string",
  "client_name": "Unnamed Verifications Inc.",
  "first_name": "John",
  "last_name": "Doe",
  "user_id": "99dd17074ac94aa9ace2621d657c7610",
  "share_url": "https://cdn.truv.com/employment.html?bridge_token=63b4af88facb40e48f517c1e8c7abdf4&order_group_id=39aa1486ccca4bc19cda071ffc1ba392",
  "created_at": "2021-04-21T21:45:14.418542Z",
  "updated_at": "2021-04-21T21:45:14.418542Z",
  "canceled_at": "2021-04-22T21:45:14.418542Z",
  "expired_at": "2021-04-24T21:45:14.418542Z",
  "is_expired": true,
  "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://citadelid-resources.s3-us-west-2.amazonaws.com/report.pdf",
      "data_source": "payroll",
      "provider": {
        "id": "truv_api",
        "name": "Sandbox Provider",
        "logo_url": "https://citadelid-resources.s3.us-west-2.amazonaws.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_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": [
                {
                  "amount": "127.01",
                  "category": "socialsec",
                  "name": "Social Security Tax"
                },
                {
                  "amount": "46.23",
                  "category": "state",
                  "name": "VA State Income Tax"
                },
                {
                  "amount": "29.7",
                  "category": "medicare",
                  "name": "Medicare Tax"
                }
              ],
              "deductions_ytd": [
                {
                  "amount": "127.01",
                  "category": "socialsec",
                  "name": "Social Security Tax"
                },
                {
                  "amount": "46.23",
                  "category": "state",
                  "name": "VA State Income Tax"
                },
                {
                  "amount": "29.7",
                  "category": "medicare",
                  "name": "Medicare Tax"
                }
              ],
              "md5sum": "03639d6a6624f69a54a88ea90bd25e9d",
              "file": "https://citadelid-resources.s3-us-west-2.amazonaws.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://citadelid-resources.s3-us-west-2.amazonaws.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": "2023-10-06",
          "external_last_updated": "2023-10-06",
          "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": "[email protected]",
            "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://citadelid-resources.s3-us-west-2.amazonaws.com/report.pdf",
    "data_source": "insurance",
    "provider": {
      "id": "truv_api",
      "name": "Sandbox Provider",
      "logo_url": "https://citadelid-resources.s3.us-west-2.amazonaws.com/providers/truv-blue.svg"
    },
    "is_suspicious": true,
    "provider_id": "geico"
  },
  "bank": {
    "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://citadelid-resources.s3-us-west-2.amazonaws.com/report.pdf",
    "data_source": "financial_accounts",
    "provider": {
      "id": "truv_api",
      "name": "Sandbox Provider",
      "logo_url": "https://citadelid-resources.s3.us-west-2.amazonaws.com/providers/truv-blue.svg"
    },
    "is_suspicious": true
  },
  "manager": {
    "email": "[email protected]",
    "name": "John Doe"
  },
  "loan": {
    "loan_number": "MUUT220700012",
    "originator_name": "John Doe",
    "originator_email": "[email protected]"
  },
  "template_id": "9b96606355b94e8abff8ed8d75aa2027",
  "fannie_voie_report_id": "b19c454a98594b4084b71e3b62873d29"
}