TRtruv
Orders

Add new employer to the existing order

Changed on

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

  • Base URL
    https://prod.truv.com
  • URL
    https://prod.truv.com/v1/orders/{id}/employers/
  • Auth
    API key in header X-Access-Client-Id and API key in header X-Access-Secret

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' | '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": "5833.33",
      "pay_frequency": "M",
      "statements": [
        {
          "id": "24d7e80942ce4ad58a93f70ce4115f5c",
          "check_number": "29205182",
          "pay_date": "2018-05-31",
          "net_pay": "12915.44",
          "net_pay_ytd": "39642.52",
          "gross_pay": "18038.33",
          "gross_pay_ytd": "55366.65",
          "bonus": "100.00",
          "commission": "12000.00",
          "hours": "173.33",
          "basis_of_pay": "S",
          "period_start": "2018-05-01",
          "period_end": "2018-05-31",
          "regular": "5833.33",
          "regular_ytd": "29166.65",
          "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": "5833.33",
              "category": "regular",
              "rate": null,
              "units": null
            },
            {
              "name": "Overtime",
              "amount": "45.00",
              "category": "overtime",
              "rate": "22.50",
              "units": "2"
            },
            {
              "name": "Commission",
              "amount": "12000.00",
              "category": "commission",
              "rate": null,
              "units": null
            },
            {
              "name": "Bonus",
              "amount": "100.00",
              "category": "bonus",
              "rate": null,
              "units": null
            },
            {
              "name": "Spot Award",
              "amount": "60.00",
              "category": "other_pay",
              "rate": null,
              "units": null
            }
          ],
          "earnings_ytd": [
            {
              "name": "Regular",
              "amount": "29166.65",
              "category": "regular",
              "rate": null,
              "units": null
            },
            {
              "name": "Overtime",
              "amount": "500.00",
              "category": "overtime",
              "rate": null,
              "units": null
            },
            {
              "name": "Commission",
              "amount": "24000.00",
              "category": "commission",
              "rate": null,
              "units": null
            },
            {
              "name": "Bonus",
              "amount": "1000.00",
              "category": "bonus",
              "rate": null,
              "units": null
            },
            {
              "name": "Spot Award",
              "amount": "700.00",
              "category": "other_pay",
              "rate": null,
              "units": null
            }
          ],
          "deductions": [
            {
              "name": "Federal Income Tax",
              "amount": "2705.75",
              "category": "federal"
            },
            {
              "name": "Social Security Tax",
              "amount": "1118.38",
              "category": "socialsec"
            },
            {
              "name": "Medicare Tax",
              "amount": "261.56",
              "category": "medicare"
            },
            {
              "name": "VA State Income Tax",
              "amount": "1037.20",
              "category": "state"
            }
          ],
          "deductions_ytd": [
            {
              "name": "Federal Income Tax",
              "amount": "8305.00",
              "category": "federal"
            },
            {
              "name": "Social Security Tax",
              "amount": "3432.73",
              "category": "socialsec"
            },
            {
              "name": "Medicare Tax",
              "amount": "802.82",
              "category": "medicare"
            },
            {
              "name": "VA State Income Tax",
              "amount": "3183.58",
              "category": "state"
            }
          ],
          "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": "29166.65",
          "bonus": "1000.00",
          "commission": "24000.00",
          "overtime": "500.00",
          "other_pay": "700.00",
          "net_pay": "39642.52",
          "gross_pay": "55366.65"
        }
      ],
      "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": "70000.00",
          "federal_tax": "5830.87",
          "social_security_wages": "70000.00",
          "social_security_tax": "4340.00",
          "medicare_wages": "70000.00",
          "medicare_tax": "1015.00",
          "gross_pay": "70000.00"
        }
      ],
      "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

  • 85952cfcaa91Revision changes
    • info

      removed the session_expired enum value from the response property for the response status

  • 85556e62dac3Revision changes
    • info

      added the optional property // to the response with the status