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.

AttributeTypeDescription
idstringUnique ID of order
productsarrayList of products selected for Order
sourcestringType of platform, internal, accio, tazworks, encompass, simplenexus, external_webpage
order_numberstringExternal ID from client
custom_fieldstringClient-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_namestringVerification agency name
first_namestringFirst name
last_namestringLast name
user_idstringUnique ID of user
share_urlstringLanding page URL to share
created_atstringISO 8601 value for when Order was created
updated_atstringISO 8601 value for when Order was last updated
canceled_atstringISO 8601 value for when Order was canceled
expired_atstringISO 8601 value for Order expiration
is_expiredboolStatus of Order expiration
initial_orderstringID of origin Order, from Order data refresh action
refresh_orderstringID of last refresh Order created by Order data refresh action
employersarray of objectsList of user employers, see Employers object
insurancearray of objectsInsurance verification metadata, see Insurance object
bankarray of objectsBank transactions metadata, see Bank object
managerarray of objectsAssociated Order manager info, see Manager object
loanarray of objectsLoan information, see Loan object
template_idstringID of template
voie_report_idstringIncome and employment verification report ID (accepted by Fannie Mae DU and Freddie Mac LPA)
voa_report_idstringAsset verification report ID
aim_check_report_idstringAIM check report ID for income calculation based on uploaded documents

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.

AttributeTypeDescription
idstringUnique ID
product_typestringType of product, see values below

income, employment, deposit_switch, pll
statusstringOrder status, see values below

pending, sent, completed, error, canceled, expired, no_data, skipped
suborder_numberstringExternal ID
created_atstringDate and time when Order was created
bridge_tokenstringUUID value of bridge_token
link_idstringLink ID for connected account
access_tokenstringAccess token to perform data refresh
pdf_reporturiVerification report in PDF format
data_sourcestringSource 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
providerarray of objectsPayroll or insurance provider, see Provider object
is_suspiciousBooleanStatus of data from source marked as suspicious, such as if detecting fraud in uploaded documents or user SSN does not match data
start_datestringEmployment start date
end_datestringEmployment end date
company_namestringCompany name
company_addressarray of objectsCompany address, see Company address object
company_domainstringCompany website domain
employmentsarray of objectsList 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.

AttributeTypeDescription
incomestringIncome amount not including commission or bonuses, only for income product
Null for employment product
income_unitstringPay 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_ratestringPayment rate per pay cycle, only for income product
Null for employment product
pay_frequencystringPay 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
statementsarray of objectsList of paystubs received from a payroll provider, only for income product, see Statements object
Null for employment product
annual_income_summaryarray of objectsAnnual income summary by years, only for income product, see Annual income summary object
Null for employment product
bank_accountsarray of objectsList of bank accounts linked to employment, only for income product, see Bank accounts object
Null for employment product
w2sarray of objectsList of W-2 forms linked to employment, only for income product, see W2s object
Null for employment product
idstringUnique ID
is_activeBooleanStatus of active employment
job_titlestringEmployee's job title
job_typestringEmployee's job type
F - Full Time
P - Part Time
S - Seasonal
D - Daily (per diem)
C - Contract
start_datedateEmployee's hire date
original_hire_datedateOriginal hire date
end_datedateEmployee's end date
external_last_updatedateIndicates date of last updated employment data from Payroll Provider
derived_fieldsarray of stringsArray of derived fields
missing_data_fieldsarray of stringsList of missing data fields from payroll response
manager_namestringSupervisor's name
profileobjectPerson's identity information
companyobjectCompany object
gse_acceptedBooleanStatus of provider eligibility from Fannie Mae Desktop Underwriter

Statements object

View the table below for information from the Statements object.

AttributeTypeDescription
idstringUnique ID
check_numberstringExternal ID of pay stub from payroll provider
pay_datedatePay date
net_paystringNet pay
net_pay_ytdstringNet pay year to date
gross_paystringGross pay
gross_pay_ytdstringGross pay year to date
bonusstringBonus
commissionstringCommission
hoursstringWork hours during pay period
basis_of_paystringBasis of pay
S - Salary
H - Hourly
D - Daily
W - Weekly
period_startdatePeriod start
period_enddatePeriod end
regularstringRegular pay
regular_ytdstringRegular salary year to date
other_pay_ytdstringAll other payment year to date
bonus_ytdstringBonus year to date
commission_ytdstringCommission year to date
overtimestringOvertime pay
overtime_ytdstringOvertime pay year to date
other_paystringAll other payment
earningsarray of objectsEarnings for this pay cycle by type
earnings_ytdarray of objectsEarnings year to date by type
deductionsarray of objectsDeductions for pay cycle by type
deductions_ytdarray of objectsDeductions year to date by type
md5sumstringMD5 hash value computed based on file content
fileuriLink to pay stub file, format is specified in the content-type
derived_fieldsarray of stringsArray of derived fields
missing_data_fieldsarray of stringsList 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.

AttributeTypeDescription
account_numberstringAccount number
routing_numberstringRouting number
account_namestringUser friendly account name
account_typestringAccount type
C - Checking account
S - Savings account
deposit_typestringDeposit type
E - Entire paycheck
P - Percentage of the paycheck
A - Fixed amount from the paycheck
deposit_valuestringDeposit value
bank_namestringBank 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.

AttributeTypeDescription
idstringUnique ID
product_typestringType of product
statusstringOrder status
suborder_numberstringExternal ID
created_atstringDate and time when Order was created
bridge_tokenstringUUID value of bridge_token
link_idstringLink ID for connected account
access_tokenstringAccess token to perform data refresh
pdf_reporturiVerification report file as a PDF
data_sourcestringSource 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
providerarray of objectsPayroll or insurance provider, see Provider object
is_suspiciousBooleanStatus of data from source marked as suspicious, such as if detecting fraud in uploaded documents or user SSN does not match data
provider_idstringPre-selected ID of insurance provider

Bank object

The bank object attributes below have type information and descriptions.

AttributeTypeDescription
idstringUnique ID
product_typestringType of product
statusstringOrder status
suborder_numberstringExternal ID
created_atstringDate and time when Order was created
bridge_tokenstringUUID value of bridge_token
link_idstringLink ID for connected account
access_tokenstringAccess token to perform data refresh
pdf_reporturiVerification report file as a PDF
data_sourcestringSource 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
providerarray of objectsPayroll or insurance provider, see Provider object
is_suspiciousBooleanStatus 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": "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"
}