Skip to main content
POST
/
v1
/
orders
/
{id}
Create a data refresh order
curl --request POST \
  --url https://prod.truv.com/v1/orders/{id}/ \
  --header 'Content-Type: application/json' \
  --header 'X-Access-Client-Id: <api-key>' \
  --header 'X-Access-Secret: <api-key>' \
  --data '
{
  "products": [
    "employment"
  ],
  "employers": [
    {
      "id": "<string>",
      "suborder_number": "<string>"
    }
  ],
  "financial_accounts": [
    {
      "id": "<string>",
      "suborder_number": "<string>"
    }
  ],
  "email": "jsmith@example.com",
  "phone": "4155554193",
  "include_recent_paystub": true,
  "reports": {
    "voa": {
      "days_requested": 380,
      "as_of_date": "2024-01-01T00:00:00.000Z",
      "large_deposit_threshold": {
        "fixed_amount": 50000,
        "sales_price": 500005,
        "qualifying_monthly_income": 50005,
        "loan_type": "FHA"
      },
      "is_voe": true,
      "request_extended_history": true,
      "account_ids": [
        "<string>"
      ]
    }
  }
}
'
{
  "id": "39aa1486ccca4bc19cda071ffc1ba392",
  "products": [
    "income"
  ],
  "source": "floify",
  "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.418Z",
  "expired_at": "2021-04-24T21:45:14.418Z",
  "is_expired": true,
  "employers": [
    {
      "id": "ad9f14440d624ec3b0f66e81e44518c7",
      "status": "pending",
      "created_at": "2021-04-21T22:12:59.346Z",
      "employments": [
        {
          "id": "24d7e80942ce4ad58a93f70ce4115f5c",
          "profile": {
            "first_name": "John",
            "last_name": "Doe",
            "home_address": {
              "street": "1 Morgan Ave",
              "city": "Los Angeles",
              "state": "CA",
              "zip": "90210",
              "country": "US"
            },
            "id": "48427a36d43c4d5aa6324bc06c692456",
            "created_at": "2022-06-07T15:00:00.000Z",
            "updated_at": "2022-06-30T15:00:00.000Z",
            "full_name": "John Doe",
            "middle_initials": "K",
            "email": "john.doe@example.com",
            "ssn": "123456789",
            "date_of_birth": "1992-03-03T00:00:00.000Z"
          },
          "company": {
            "name": "Facebook Demo",
            "address": {
              "street": "1 Morgan Ave",
              "city": "Los Angeles",
              "state": "CA",
              "zip": "90210",
              "country": "US"
            },
            "phone": "6503087300",
            "ein": "12-345678"
          },
          "income": "70000.00",
          "income_unit": "YEARLY",
          "pay_rate": "6500.00",
          "pay_frequency": "M",
          "statements": [
            {
              "pay_date": "2018-05-15T00:00:00.000Z",
              "id": "24d7e80942ce4ad58a93f70ce4115f5c",
              "check_number": "29205182",
              "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-01T00:00:00.000Z",
              "period_end": "2018-05-15T00:00:00.000Z",
              "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"
            }
          ],
          "is_active": false,
          "job_title": "PR associate",
          "job_type": "F",
          "start_date": "2018-01-01T00:00:00.000Z",
          "original_hire_date": "2017-06-21T00:00:00.000Z",
          "end_date": "2023-12-25",
          "external_last_updated": "2023-12-25",
          "dates_from_statements": false,
          "derived_fields": [
            "is_active"
          ],
          "missing_data_fields": [
            "w2s"
          ],
          "manager_name": "Jenny McDouglas"
        }
      ],
      "product_type": "income",
      "suborder_number": "133982343355",
      "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-24T00:00:00.000Z",
      "end_date": "2019-11-27T00:00:00.000Z",
      "company_name": "Facebook Demo",
      "company_address": {
        "street": "1 Hacker Way",
        "city": "Menlo Park",
        "state": "CA",
        "zip": "94025"
      },
      "company_domain": "facebook.com",
      "company_logo": "https://cdn.truv.com/company_logos/facebook.svg"
    }
  ],
  "order_number": "1534332",
  "custom_field": "<string>",
  "bridge_token": "e4100fccdae94691b4414c7306220c06",
  "updated_at": "2021-04-21T21:45:14.418Z",
  "canceled_at": "2021-04-22T21:45:14.418Z",
  "completed_at": "2021-04-22T21:45:14.418Z",
  "user_consent_at": "2021-04-21T21:45:14.418Z",
  "initial_order": "f5dc0239e2094dbc90ab2edc1918a9df",
  "refresh_order": "9b96606355b94e8abff8ed8d75aa2027",
  "insurance": {
    "id": "ad9f14440d624ec3b0f66e81e44518c7",
    "status": "pending",
    "created_at": "2021-04-21T22:12:59.346Z",
    "product_type": "insurance",
    "suborder_number": "133982343355",
    "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",
      "status": "pending",
      "created_at": "2021-04-21T22:12:59.346Z",
      "product_type": "transactions",
      "suborder_number": "133982343355",
      "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": "24d7e80942ce4ad58a93f70ce4115f5c",
          "type": "CHECKING",
          "subtype": "MONEY_MARKET",
          "mask": "6789",
          "balance": "5000.00",
          "owners": [
            {
              "full_name": "John Doe"
            }
          ]
        }
      ]
    }
  ],
  "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": "c505e0f1b4134fdc853fc87e7d2cc4a5",
    "is_closed": false
  },
  "template_id": "9b96606355b94e8abff8ed8d75aa2027",
  "cc_emails": [
    "jsmith@example.com"
  ],
  "short_share_url": "https://truv.com/s/BIlEyh1A",
  "voie_report_id": "b19c454a98594b4084b71e3b62873d29",
  "voa_report_id": "b19c454a98594b4084b71e3b62873d29",
  "income_insights_report_id": "b19c454a98594b4084b71e3b62873d29",
  "aim_check_report_id": "FM-1234-39aa1486ccca4bc19cda071ffc1ba392",
  "notes": "To be processed by John Doe"
}

Authorizations

​
X-Access-Client-Id
string
header
required

Client ID

​
X-Access-Secret
string
header
required

Client Access Key

Path Parameters

​
id
string
required

Order ID received from the POST request

Body

application/json
​
products
enum<string>[]

Indicates the type of product to use for the data refresh order. For the "income" type orders the data refresh order can be "income" or "employment" type. For the "employment" type orders the data refresh order can be only "employment" type.

Required array length: 1 element
Available options:
employment,
income,
insurance,
transactions,
assets
​
employers
object[]

List of employers to include in the new refresh order data.

​
financial_accounts
object[]

List of financial accounts to include in the new refresh order data.

​
manager
object

Associate new order manager info with a new data refresh order.

​
email
string<email>

Subject's email

​
phone
string

Subject's phone number

Example:

"4155554193"

​
include_recent_paystub
boolean

A boolean parameter to include the latest statement in the employment report

​
reports
object

Reports parameters

Response

​
id
string
required

Unique ID

Example:

"39aa1486ccca4bc19cda071ffc1ba392"

​
products
enum<string>[]
required

Types of products selected for the order

Available options:
income,
employment,
deposit_switch,
pll,
insurance,
transactions,
assets
​
source
enum<string>
required

Type of the platform (internal, accio, etc.)

Available options:
floify,
besmartee,
lenderlogix,
encompass_consumer_connect,
byte,
core_logic,
xactus,
constellation,
banno,
mx,
q2,
clutch,
accio,
encompass,
tpo_connect,
darkmatter,
tazworks,
internal,
simplenexus,
external_webpage,
individual,
alkami,
blue_sage,
lodasoft,
blend,
tidalwave,
self_signup
​
client_name
string
required

Verification agency name

Example:

"Unnamed Verifications Inc."

​
first_name
string
required

First name

Example:

"John"

​
last_name
string
required

Last name

Example:

"Doe"

​
user_id
string
required

Unique Truv ID of the user.

Example:

"99dd17074ac94aa9ace2621d657c7610"

​
share_url
string | null
required

Landing page URL to share

Example:

"https://cdn.truv.com/employment.html?bridge_token=63b4af88facb40e48f517c1e8c7abdf4&order_group_id=39aa1486ccca4bc19cda071ffc1ba392"

​
created_at
string<date-time>
required

Date and time when order was created

Example:

"2021-04-21T21:45:14.418Z"

​
expired_at
string<date-time>
required

Date and time when order would expire

Example:

"2021-04-24T21:45:14.418Z"

​
is_expired
boolean
required

If order is already expired

​
employers
object[]
required

List of employers

​
order_number
string | null

External ID

Example:

"1534332"

​
custom_field
string | null

User provided custom field. Must be enabled in the customization section.

​
bridge_token
string

UUID value of bridge token

Example:

"e4100fccdae94691b4414c7306220c06"

​
updated_at
string<date-time>

Date and time when order was updated

Example:

"2021-04-21T21:45:14.418Z"

​
canceled_at
string<date-time> | null

Date and time when order was canceled

Example:

"2021-04-22T21:45:14.418Z"

​
completed_at
string<date-time> | null

Date and time when order was successfully completed

Example:

"2021-04-22T21:45:14.418Z"

​
user_consent_at
string<date-time> | null

Date and time when explicit user consent was given

Example:

"2021-04-21T21:45:14.418Z"

​
initial_order
string | null

ID of an origin order if the order was created by the order data refresh operation

Example:

"f5dc0239e2094dbc90ab2edc1918a9df"

​
refresh_order
string | null

ID of the last refresh order created by the order data refresh operation for the order

Example:

"9b96606355b94e8abff8ed8d75aa2027"

​
insurance
object

Insurance verification meta data

​
manager
object

Order manager info associated with an order.

​
financial_accounts
object[] | null

List of financial accounts

​
loan
object

Loan Information

​
template_id
string | null

ID of the template

Example:

"9b96606355b94e8abff8ed8d75aa2027"

​
cc_emails
string<email>[]

A list of email addresses that will receive carbon copies (CC) of order status updates.

Maximum array length: 15
​
short_share_url
string | null

Shortened verification URL to share

Example:

"https://truv.com/s/BIlEyh1A"

​
voie_report_id
string | null

GSE accepted income and employment verification report ID

Example:

"b19c454a98594b4084b71e3b62873d29"

​
voa_report_id
string | null

Verification of Assets report ID

Example:

"b19c454a98594b4084b71e3b62873d29"

​
income_insights_report_id
string | null

Income Insights report ID

Example:

"b19c454a98594b4084b71e3b62873d29"

​
aim_check_report_id
string | null

AIM check report ID

Example:

"FM-1234-39aa1486ccca4bc19cda071ffc1ba392"

​
notes
string | null

Free text field for notes associated with the order

Required string length: 1 - 2000
Example:

"To be processed by John Doe"