Skip to main content
POST
/
v1
/
orders
/
{id}
/
employers
Add new employer to the existing order
curl --request POST \
  --url https://prod.truv.com/v1/orders/{id}/employers/ \
  --header 'Content-Type: application/json' \
  --header 'X-Access-Client-Id: <api-key>' \
  --header 'X-Access-Secret: <api-key>' \
  --data '
{
  "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"
}
'
{
  "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"
}

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
​
start_date
string<date>

Job start date

Example:

"2019-08-24T00:00:00.000Z"

​
end_date
string<date>

Job end date

Example:

"2019-11-27T00:00:00.000Z"

​
company_name
string

Company name

Example:

"Facebook Demo"

​
company_address
object

Company address

​
company_domain
string

Company website domain

Example:

"facebook.com"

Company logo URL

Example:

"https://cdn.truv.com/company_logos/facebook.svg"

​
suborder_number
string

External ID

Example:

"133982343355"

​
company_mapping_id
string

Company mapping ID

Example:

"self_employed"

Response

​
id
string
required

Unique ID

Example:

"ad9f14440d624ec3b0f66e81e44518c7"

​
status
enum<string>
required

Order status

Available options:
pending,
sent,
completed,
error,
canceled,
expired,
no_data,
skipped
Example:

"pending"

​
created_at
string
required

Date and time when order was created

Example:

"2021-04-21T22:12:59.346Z"

​
employments
object[] | null
required

List of employments

​
product_type
enum<string>

Type of the product.

Available options:
income,
employment,
deposit_switch,
pll
Example:

"income"

​
suborder_number
string | null

External ID

Example:

"133982343355"

​
bridge_token
string

UUID value of bridge token

Example:

"e4100fccdae94691b4414c7306220c06"

​
link_id
string | null

Link ID for the connected account

Example:

"e4100fccdae94691b4414c7306220c06"

​
access_token
string | null

Access token to perform data refresh

Example:

"e4100fccdae94691b4414c7306220c06"

​
pdf_report
string<uri>

Verification report in PDF format

Example:

"https://cdn.truv.com/report.pdf"

​
data_source
enum<string> | null

Source of data: payroll - payroll provider parsing, docs - user uploaded documents, insurance - insurance data, financial_accounts - bank data, tax - tax documents, scoring_attributes - transactions scoring attributes report.

Available options:
payroll,
docs,
tax,
financial_accounts,
null
Example:

"payroll"

​
provider
object

Payroll or insurance provider

​
is_suspicious
boolean

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

​
start_date
string | null

Employment start date

Example:

"2019-08-24T00:00:00.000Z"

​
end_date
string | null

Employment start date

Example:

"2019-11-27T00:00:00.000Z"

​
company_name
string | null

Company name

Example:

"Facebook Demo"

​
company_address
object

Company address

​
company_domain
string | null

Company website domain

Example:

"facebook.com"

​
company_logo
string<uri> | null

Company logo URL

Example:

"https://cdn.truv.com/company_logos/facebook.svg"