Account Links4

Accounts2

Bank Accounts1

Bank Statements1

Bridge Token1

Companies and Data Providers5

Customization Templates5

Data Refresh2

DDS Reports1

Deposit Switch Reports2

Document Collections9

Employment2

Identity1

Income Insights Reports2

Income Report1

Insurance Reports3

Investments1

Key Management2

Liabilities1

Orders13

Parsed Documents2

Pay Statements2

Recurring Transactions1

Reports2

Scoring Attributes2

Shifts1

Tasks2

Tax Documents2

Transactions1

Uploaded Documents2

Users5

VOA Reports2

VOIE Reports2

Webhooks6

Orders

Add new employer to the existing order

The endpoint allows to add new employer to the existing order. The order should not be expired or canceled.

An order holds at most 5 employers, counting the ones sent when the order was created. Adding one past the limit returns 400.

post/v1/orders/{id}/employers/

Request body

start_datestring date

Job start date

end_datestring date

Job end date

company_namestring

Company name

company_domainstring

Company website domain

company_logostring uri

Company logo URL

suborder_numberstring

External ID

company_mapping_idstring

Company mapping ID

Example request

{
  "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",
  "company_logo": "https://cdn.truv.com/company_logos/facebook.svg",
  "suborder_number": "133982343355",
  "company_mapping_id": "self_employed"
}

Response

idstring required

Unique ID

product_type'income' | 'employment' | 'deposit_switch' | 'pll'

Type of the product.

Order status

suborder_numberstring nullable

External ID

created_atstring required

Date and time when order was created

bridge_tokenstring

UUID value of bridge token

link_idstring nullable

Link ID for the connected account

access_tokenstring nullable

Access token to perform data refresh

pdf_reportstring uri nullable

Verification report in PDF format

data_source'payroll' | 'docs' | 'tax' | 'financial_accounts' | 'null' nullable

Source of data: payroll - payroll provider parsing, docs - user uploaded documents, tax - tax documents, financial_accounts - bank data.

is_suspiciousboolean

Flag to indicate if the data from the source is suspicious. E.g. fraud detected in uploaded documents or SSN of the user does not match with the data

Status of the most recent task for the connection. Terminal statuses are done, error, login_error, account_locked, mfa_error, config_error, no_data, unavailable, unable_to_reset, and not_supported. The remaining values are in-progress statuses that appear while a verification is still running. Returns null when no task exists for the connection yet.

start_datestring nullable

Employment start date

end_datestring nullable

Employment start date

company_namestring nullable

Company name

company_domainstring nullable

Company website domain

company_logostring uri nullable

Company logo URL

Example response

{
  "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://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"
  },
  "last_task_status": "done",
  "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",
  "company_logo": "https://cdn.truv.com/company_logos/facebook.svg",
  "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.70",
              "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.70",
              "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"
        }
      ],
      "id": "24d7e80942ce4ad58a93f70ce4115f5c",
      "job_title": "PR associate",
      "job_type": "F",
      "start_date": "2018-01-01",
      "original_hire_date": "2017-06-21",
      "external_last_updated": "2026-04-23",
      "employed_in_role": "8 years 3 months",
      "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-30T15:00:00Z",
        "first_name": "John",
        "last_name": "Doe",
        "full_name": "John Doe",
        "middle_initials": "K",
        "email": "john.doe@example.com",
        "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": "770493581"
      }
    }
  ]
}

Changes

Changed in 3 of the 11 revisions of this API.32839

Aug 13, 202685556e62dac31See the full diff
- ○
  added the optional property employments/items/employed_in_role to the response with the 201 status
  response-optional-property-added
Jul 27, 2026f7c0138755162837See the full diff
- ●
  the company_address/city request property's maxLength was set to 64
  request-property-max-length-set
- ●
  the company_address/state request property's maxLength was set to 32
  request-property-max-length-set
- ●
  the company_address/street request property's maxLength was set to 255
  request-property-max-length-set
- ●
  the company_address/zip request property's maxLength was set to 10
  request-property-max-length-set
- ●
  the company_domain request property's maxLength was set to 128
  request-property-max-length-set
- ●
  the company_logo request property's maxLength was set to 512
  request-property-max-length-set
- ●
  the company_mapping_id request property's maxLength was set to 64
  request-property-max-length-set
- ●
  the company_name request property's maxLength was set to 128
  request-property-max-length-set
- ●
  the suborder_number request property's maxLength was set to 512
  request-property-max-length-set
- ●
  added the new C enum value to the employments/items/statements/items/basis_of_pay response property for the response status 201
  response-property-enum-value-added
- ●
  added the new account_locked enum value to the last_task_status response property for the response status 201
  response-property-enum-value-added
- ●
  added the new config_error enum value to the last_task_status response property for the response status 201
  response-property-enum-value-added
- ●
  added the new done enum value to the last_task_status response property for the response status 201
  response-property-enum-value-added
- ●
  added the new error enum value to the last_task_status response property for the response status 201
  response-property-enum-value-added
- ●
  added the new full_parse enum value to the last_task_status response property for the response status 201
  response-property-enum-value-added
- ●
  added the new login enum value to the last_task_status response property for the response status 201
  response-property-enum-value-added
- ●
  added the new login_error enum value to the last_task_status response property for the response status 201
  response-property-enum-value-added
- ●
  added the new mfa enum value to the last_task_status response property for the response status 201
  response-property-enum-value-added
- ●
  added the new mfa_error enum value to the last_task_status response property for the response status 201
  response-property-enum-value-added
- ●
  added the new new enum value to the last_task_status response property for the response status 201
  response-property-enum-value-added
- ●
  added the new no_data enum value to the last_task_status response property for the response status 201
  response-property-enum-value-added
- ●
  added the new not_supported enum value to the last_task_status response property for the response status 201
  response-property-enum-value-added
- ●
  added the new parse enum value to the last_task_status response property for the response status 201
  response-property-enum-value-added
- ●
  added the new session_expired enum value to the last_task_status response property for the response status 201
  response-property-enum-value-added
- ●
  added the new switch_deposit enum value to the last_task_status response property for the response status 201
  response-property-enum-value-added
- ●
  added the new unable_to_reset enum value to the last_task_status response property for the response status 201
  response-property-enum-value-added
- ●
  added the new unavailable enum value to the last_task_status response property for the response status 201
  response-property-enum-value-added
- ●
  added the new undefined enum value to the last_task_status response property for the response status 201
  response-property-enum-value-added
- ○
  the employments/items/annual_income_summary/items/bonus response's property pattern ^-?\d{1,10}\.\d{2}$ was added for the status 201
  response-property-pattern-added
- ○
  the employments/items/annual_income_summary/items/commission response's property pattern ^-?\d{1,10}\.\d{2}$ was added for the status 201
  response-property-pattern-added
- ○
  the employments/items/annual_income_summary/items/gross_pay response's property pattern ^-?\d{1,10}\.\d{2}$ was added for the status 201
  response-property-pattern-added
- ○
  the employments/items/annual_income_summary/items/net_pay response's property pattern ^-?\d{1,10}\.\d{2}$ was added for the status 201
  response-property-pattern-added
- ○
  the employments/items/annual_income_summary/items/other_pay response's property pattern ^-?\d{1,10}\.\d{2}$ was added for the status 201
  response-property-pattern-added
- ○
  the employments/items/annual_income_summary/items/overtime response's property pattern ^-?\d{1,10}\.\d{2}$ was added for the status 201
  response-property-pattern-added
- ○
  the employments/items/annual_income_summary/items/regular response's property pattern ^-?\d{1,10}\.\d{2}$ was added for the status 201
  response-property-pattern-added
- ○
  the employments/items/bank_accounts/items/deposit_value response's property pattern ^-?\d{1,10}\.\d{2}$ was added for the status 201
  response-property-pattern-added
- ○
  the employments/items/income response's property pattern ^-?\d{1,10}\.\d{2}$ was added for the status 201
  response-property-pattern-added
- ○
  the employments/items/pay_rate response's property pattern ^-?\d{1,10}\.\d{2}$ was added for the status 201
  response-property-pattern-added
- ○
  the employments/items/profile/ssn response's property pattern ^(\d{4}|\d{9})$ was added for the status 201
  response-property-pattern-added
- ○
  the employments/items/statements/items/bonus response's property pattern ^-?\d{1,10}\.\d{2}$ was added for the status 201
  response-property-pattern-added
- ○
  the employments/items/statements/items/bonus_ytd response's property pattern ^-?\d{1,10}\.\d{2}$ was added for the status 201
  response-property-pattern-added
- ○
  the employments/items/statements/items/commission response's property pattern ^-?\d{1,10}\.\d{2}$ was added for the status 201
  response-property-pattern-added
- ○
  the employments/items/statements/items/commission_ytd response's property pattern ^-?\d{1,10}\.\d{2}$ was added for the status 201
  response-property-pattern-added
- ○
  the employments/items/statements/items/deductions/items/amount response's property pattern ^-?\d{1,10}\.\d{2}$ was added for the status 201
  response-property-pattern-added
- ○
  the employments/items/statements/items/deductions_ytd/items/amount response's property pattern ^-?\d{1,10}\.\d{2}$ was added for the status 201
  response-property-pattern-added
- ○
  the employments/items/statements/items/earnings/items/amount response's property pattern ^-?\d{1,10}\.\d{2}$ was added for the status 201
  response-property-pattern-added
- ○
  the employments/items/statements/items/earnings_ytd/items/amount response's property pattern ^-?\d{1,10}\.\d{2}$ was added for the status 201
  response-property-pattern-added
- ○
  the employments/items/statements/items/gross_pay response's property pattern ^-?\d{1,10}\.\d{2}$ was added for the status 201
  response-property-pattern-added
- ○
  the employments/items/statements/items/gross_pay_ytd response's property pattern ^-?\d{1,10}\.\d{2}$ was added for the status 201
  response-property-pattern-added
- ○
  the employments/items/statements/items/hours response's property pattern ^-?\d{1,10}\.\d{2}$ was added for the status 201
  response-property-pattern-added
- ○
  the employments/items/statements/items/net_pay response's property pattern ^-?\d{1,10}\.\d{2}$ was added for the status 201
  response-property-pattern-added
- ○
  the employments/items/statements/items/net_pay_ytd response's property pattern ^-?\d{1,10}\.\d{2}$ was added for the status 201
  response-property-pattern-added
- ○
  the employments/items/statements/items/other_pay response's property pattern ^-?\d{1,10}\.\d{2}$ was added for the status 201
  response-property-pattern-added
- ○
  the employments/items/statements/items/other_pay_ytd response's property pattern ^-?\d{1,10}\.\d{2}$ was added for the status 201
  response-property-pattern-added
- ○
  the employments/items/statements/items/overtime response's property pattern ^-?\d{1,10}\.\d{2}$ was added for the status 201
  response-property-pattern-added
- ○
  the employments/items/statements/items/overtime_ytd response's property pattern ^-?\d{1,10}\.\d{2}$ was added for the status 201
  response-property-pattern-added
- ○
  the employments/items/statements/items/regular response's property pattern ^-?\d{1,10}\.\d{2}$ was added for the status 201
  response-property-pattern-added
- ○
  the employments/items/statements/items/regular_ytd response's property pattern ^-?\d{1,10}\.\d{2}$ was added for the status 201
  response-property-pattern-added
- ○
  the employments/items/w2s/items/federal_tax response's property pattern ^-?\d{1,10}\.\d{2}$ was added for the status 201
  response-property-pattern-added
- ○
  the employments/items/w2s/items/gross_pay response's property pattern ^-?\d{1,10}\.\d{2}$ was added for the status 201
  response-property-pattern-added
- ○
  the employments/items/w2s/items/medicare_tax response's property pattern ^-?\d{1,10}\.\d{2}$ was added for the status 201
  response-property-pattern-added
- ○
  the employments/items/w2s/items/medicare_wages response's property pattern ^-?\d{1,10}\.\d{2}$ was added for the status 201
  response-property-pattern-added
- ○
  the employments/items/w2s/items/social_security_tax response's property pattern ^-?\d{1,10}\.\d{2}$ was added for the status 201
  response-property-pattern-added
- ○
  the employments/items/w2s/items/social_security_wages response's property pattern ^-?\d{1,10}\.\d{2}$ was added for the status 201
  response-property-pattern-added
- ○
  the employments/items/w2s/items/wages response's property pattern ^-?\d{1,10}\.\d{2}$ was added for the status 201
  response-property-pattern-added
Jul 26, 2026e58688835e2531See the full diff
- ▲
  the response property employments/items/profile/full_name became nullable for the status 201
  response-property-became-nullable
- ▲
  the response property employments/items/profile/ssn became nullable for the status 201
  response-property-became-nullable
- ▲
  the response property provider/id became nullable for the status 201
  response-property-became-nullable
- ○
  added the optional property last_task_status to the response with the 201 status
  response-optional-property-added

Full history