Orders

Manage personal landing pages for users to connect accounts with Orders.

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

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

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

Bank income insights report ID

aim_check_report_id

string

AIM check report ID for income calculation based on uploaded documents

📘

Retrieve a PDF version of the report

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

Company address object

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

AttributeTypeDescription
streetstringStreet
citystringCity
statestringState
zipstringZip
countrystringCountry

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.

AttributeTypeDescription
idstringProvider unique ID
namestringProvider name
logo_urluriProvider 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.

AttributeTypeDescription
idstringUnique ID
yearintegerIncome report year
regularstringRegular salary
bonusstringBonus
commissionstringCommission
overtimestringOvertime pay
other_paystringAll other payment forms
net_paystringNet pay
gross_paystringGross 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.

AttributeTypeDescription
fileuriLink to W2 report file, format is specified in the content-type
md5sumstringMD5 hash value computed based on file content
yearintegerYear
wagesstringWages, tips, other compensation (Section 1)
federal_taxstringFederal income tax withheld (Section 2)
social_security_wagesstringSocial security wages (Section 3)
social_security_taxstringSocial security tax withheld (Section 4)
medicare_wagesstringMedicare wages (Section 5)
medicare_taxstringMedicare tax withheld (Section 6)
gross_paystringGross pay

Company object

This table covers values within the company object.

AttributeTypeDescription
namestringCompany name
addressobjectAddress object
phonestringCompany phone number
einstringEmployer Identification Number
Address object

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

AttributeTypeDescription
streetstringStreet
citystringCity
statestringState
zipstringZip
countrystringCountry

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.

AttributeTypeDescription
emailstringEmail or Order manager
namestringName of Order manager

Loan object

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

AttributeTypeDescription
loan_numberstringLoan identifier
external_idstringExternal loan ID (e.g. from POS)
originator_namestringName of loan originator
originator_emailstringEmail of loan originator
loan_processor_namestringName of the loan processor
loan_processor_emailstringEmail 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",
  "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://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": [
                {
                  "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://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": "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": "[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"
  },
  "manager": {
    "email": "[email protected]",
    "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://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
    }
  ],
  "loan": {
    "loan_number": "MUUT220700012",
    "originator_name": "John Doe",
    "originator_email": "[email protected]",
    "loan_processor_name": "John Doe",
    "loan_processor_email": "[email protected]",
    "external_id": "c505e0f1-b413-4fdc-853f-c87e7d2cc4a5"
  },
  "template_id": "9b96606355b94e8abff8ed8d75aa2027",
  "cc_emails": [
    "[email protected]"
  ],
  "voie_report_id": "b19c454a98594b4084b71e3b62873d29",
  "voa_report_id": "b19c454a98594b4084b71e3b62873d29",
  "aim_check_report_id": "FM-1234-39aa1486ccca4bc19cda071ffc1ba392"
}