Sign in
OpenAPI 3.0.12026-08-1991238713.6 KB

1884c5bfe3a5

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.

status'pending' | 'sent' | 'completed' | 'error' | 'canceled' | 'expired' | 'no_data' | 'skipped' required

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

last_task_status'done' | 'error' | 'login_error' | 'account_locked' | 'mfa_error' | 'config_error' | 'no_data' | 'unavailable' | 'unable_to_reset' | 'not_supported' | 'new' | 'login' | 'mfa' | 'parse' | 'full_parse' | 'switch_deposit' | 'session_expired' | 'null' nullable

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"
      }
    }
  ]
}