Skip to main content
POST
/
v1
/
orders
Create an order
curl --request POST \
  --url https://prod.truv.com/v1/orders/ \
  --header 'Content-Type: application/json' \
  --header 'X-Access-Client-Id: <api-key>' \
  --header 'X-Access-Secret: <api-key>' \
  --data '
{
  "products": [
    "employment"
  ],
  "first_name": "John",
  "last_name": "Doe",
  "ssn": "222233333",
  "email": "jsmith@example.com",
  "phone": "4155554193",
  "order_number": "1534332",
  "external_user_id": "user_12345",
  "employers": [
    {
      "start_date": "2019-08-24T00:00:00.000Z",
      "end_date": "2019-11-27T00:00:00.000Z",
      "company_name": "Facebook Demo",
      "company_domain": "facebook.com",
      "company_logo": "https://cdn.truv.com/company_logos/facebook.svg",
      "suborder_number": "133982343355",
      "company_mapping_id": "self_employed",
      "data_sources": [
        "payroll"
      ]
    }
  ],
  "financial_institutions": [
    {
      "id": "<string>",
      "name": "Chase",
      "suborder_number": "133982343355"
    }
  ],
  "insurance": {
    "provider_id": "geico"
  },
  "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
  },
  "reports": {
    "voa": {
      "days_requested": 380,
      "as_of_date": "2024-12-31T00: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
    }
  },
  "template_id": "9b96606355b94e8abff8ed8d75aa2027",
  "custom_field": "<string>",
  "cc_emails": [
    "jsmith@example.com"
  ],
  "notes": "To be processed by John Doe",
  "source": "floify",
  "notification_settings": {
    "suppress_user_notifications": false,
    "first_notification_delay_hours": 0
  },
  "locale": "es"
}
'
{
  "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

Body

application/json

An Order for a user to link an account

​
products
enum<string>[]
required

Types of products selected for the order

Available options:
income,
employment,
deposit_switch,
pll,
insurance,
transactions,
assets
​
first_name
string
required

First name

Example:

"John"

​
last_name
string
required

Last name

Example:

"Doe"

​
ssn
string

User's SSN. Should be 4 or 9 digits length.

Example:

"222233333"

​
email
string<email>

Subject's email

​
phone
string

Subject's phone number

Example:

"4155554193"

​
order_number
string

External ID for the order.

Example:

"1534332"

​
external_user_id
string | null

External user identifier. If not provided, order_number will be used for backwards compatibility.

Maximum string length: 512
Example:

"user_12345"

​
employers
object[]

List of employers

​
financial_institutions
object[]

List of financial institutions

Maximum array length: 5
​
insurance
object

Insurance verification additional parameters

​
manager
object

Associate your order manager info with an order.

​
loan
object

Loan Information

​
reports
object

Reports parameters

​
template_id
string

ID of the template

Example:

"9b96606355b94e8abff8ed8d75aa2027"

​
custom_field
string

Client provided custom field. Must be enabled in the dashboard customization section.

​
cc_emails
string<email>[]

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

Maximum array length: 15
​
notes
string | null

Free text field for notes associated with the order

Required string length: 1 - 2000
Example:

"To be processed by John Doe"

​
source
enum<string>

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
​
notification_settings
object

Configuration for order notifications

​
locale
enum<string>

Locale parameter (ISO 639) for regional customization of the order

Available options:
en,
ar,
cmn,
es,
fa,
hy,
km,
zh,
hi,
hmn,
ja,
ko,
lo,
ium,
pa,
pt,
ru,
so,
tl,
th,
uk,
vi
Example:

"es"

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"