---
title: "Add new employer to the existing order"
method: POST
path: "/v1/orders/{id}/employers/"
tags: ["Orders"]
---

# Add new employer to the existing order

`POST /v1/orders/{id}/employers/`

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

## Request body

- EmployerAdd
  - `start_date` string, date — Job start date
  - `end_date` string, date — Job end date
  - `company_name` string — Company name
  - `company_address` object — Company address
    - `street` string, required — Company location street. Returned exactly as provided when the order was created, and may contain multiple lines separated by `\n`.
    - `city` string, required — Company location city. Returned exactly as provided when the order was created.
    - `state` string, required — Company location state. Typically a 2-letter state code; international region codes such as `NSW` are also accepted. Returned exactly as provided when the order was created.
    - `zip` string, required — Company location zip code. Typically a 5-digit US ZIP code; ZIP+4 and non-US postal codes also occur. Returned exactly as provided when the order was created.
  - `company_domain` string — Company website domain
  - `company_logo` string, uri — Company logo URL
  - `suborder_number` string — External ID
  - `company_mapping_id` string — Company mapping ID

## Response `201`

- EmployerResponse
  - `id` string, 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_number` string, nullable — External ID
  - `created_at` string, required — Date and time when order was created
  - `bridge_token` string — UUID value of bridge token
  - `link_id` string, nullable — Link ID for the connected account
  - `access_token` string, nullable — Access token to perform data refresh
  - `pdf_report` string, 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.
  - `provider` object, nullable — Payroll or insurance provider
    - `id` string, nullable, required — Provider id
    - `name` string, required — Provider name
    - `logo_url` string, uri, nullable — Provider logo url
  - `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
  - `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](/api-reference/tasks/lifecycle) 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_date` string, nullable — Employment start date
  - `end_date` string, nullable — Employment start date
  - `company_name` string, nullable — Company name
  - `company_address` object, nullable — Company address
    - `street` string, required — Company location street. Returned exactly as provided when the order was created, and may contain multiple lines separated by `\n`.
    - `city` string, required — Company location city. Returned exactly as provided when the order was created.
    - `state` string, required — Company location state. Typically a 2-letter state code; international region codes such as `NSW` are also accepted. Returned exactly as provided when the order was created.
    - `zip` string, required — Company location zip code. Typically a 5-digit US ZIP code; ZIP+4 and non-US postal codes also occur. Returned exactly as provided when the order was created.
  - `company_domain` string, nullable — Company website domain
  - `company_logo` string, uri, nullable — Company logo URL
  - `employments` object[], nullable, required — List of employments
    - `income` string, decimal, nullable — Income amount not including commission or bonuses (only for income product)
    - `income_unit` 'YEARLY' | 'MONTHLY' | 'WEEKLY' | 'DAILY' | 'HOURLY' | 'null', nullable — The pay interval the income field refers to: * `YEARLY` - Annual income, * `MONTHLY` - Monthly income, * `WEEKLY` - Weekly income, * `DAILY` - Daily income, * `HOURLY` - Hourly income (only for income product)
    - `pay_rate` string, decimal, nullable — Payment rate per pay cycle (only for income product)
    - `pay_frequency` 'M' | 'SM' | 'W' | 'BW' | 'A' | 'SA' | 'C' | 'null', nullable — Pay frequency: * `M` - Monthly, * `SM` - Semi-Monthly, * `W` - Weekly, * `BW` - Bi-Weekly, * `A` - Annually, * `SA` - Semiannually, * `C` - Commission (only for income product)
    - `statements` Statement[] — List of paystubs received from a payroll provider (only for income product)
      - `id` string — Unique ID
      - `check_number` string, string, nullable — External ID of pay stub from the payroll provider
      - `pay_date` string, date, required — Pay Date
      - `net_pay` string, decimal, nullable — Net pay
      - `net_pay_ytd` string, decimal, nullable — Net pay year to date
      - `gross_pay` string, decimal, nullable — Gross pay
      - `gross_pay_ytd` string, decimal, nullable — Gross pay year to date
      - `bonus` string, decimal, nullable — Bonus
      - `commission` string, decimal, nullable — Commission
      - `hours` string, decimal, nullable — Work hours during a pay period
      - `basis_of_pay` 'S' | 'H' | 'D' | 'W' | 'M' | 'C' | 'null', nullable — Basis of pay: * `S` - Salary, * `H` - Hourly, * `D` - Daily, * `W` - Weekly, * `M` - Monthly, * `C` - Contract,
      - `period_start` string, date, nullable — Period start
      - `period_end` string, date, nullable — Period end
      - `regular` string, decimal, nullable — Regular pay
      - `regular_ytd` string, decimal, nullable — Regular salary year to date
      - `other_pay_ytd` string, decimal, nullable — All other pays year to date
      - `bonus_ytd` string, decimal, nullable — Bonus year to date
      - `commission_ytd` string, decimal, nullable — Commission year to date
      - `overtime` string, decimal, nullable — Overtime pay
      - `overtime_ytd` string, decimal, nullable — Overtime pay year to date
      - `other_pay` string, decimal, nullable — All other pays
      - `earnings` object[], nullable — Earnings for this pay cycle by type
        - `name` string, required — Name of earnings
        - `amount` string, decimal, required — Amount of earnings
        - `category` 'regular' | 'overtime' | 'bonus' | 'commission' | 'other_pay', required — Category of earnings
        - `rate` string, decimal, nullable — Rate of earnings. The number of decimal places varies by payroll provider (`"30.29"`, `"3334.6200"`, `"2"`) and the value can be negative.
        - `units` string, decimal, nullable — Units of earnings. The number of decimal places varies by payroll provider (`"2"`, `"1.0000"`, `"842.5"`) and the value can be negative.
      - `earnings_ytd` object[], nullable — Earnings year to date by type
        - `name` string, required — Name of earnings
        - `amount` string, decimal, required — Amount of earnings
        - `category` 'regular' | 'overtime' | 'bonus' | 'commission' | 'other_pay', required — Category of earnings
        - `rate` string, decimal, nullable — Rate of earnings. The number of decimal places varies by payroll provider (`"30.29"`, `"3334.6200"`, `"2"`) and the value can be negative.
        - `units` string, decimal, nullable — Units of earnings. The number of decimal places varies by payroll provider (`"2"`, `"1.0000"`, `"842.5"`) and the value can be negative.
      - `deductions` object[], nullable — Deductions for this pay cycle by type
        - `name` string, required — Name of the deduction
        - `amount` string, decimal, required — Amount of the deduction
        - `category` 'memo' | 'medicare' | 'retirement' | 'socialsec' | 'federal' | 'state' | 'benefit' | 'garnishment' | 'local' | 'other', required — Category of the deduction
      - `deductions_ytd` object[], nullable — Deductions year to date by type
        - `name` string, required — Name of the deduction
        - `amount` string, decimal, required — Amount of the deduction
        - `category` 'memo' | 'medicare' | 'retirement' | 'socialsec' | 'federal' | 'state' | 'benefit' | 'garnishment' | 'local' | 'other', required — Category of the deduction
      - `md5sum` string, string, nullable — MD5 hash value computed based on the file content
      - `file` string, uri, nullable — Link to a pay stub file (format is specified in the content-type)
      - `derived_fields` string[] — Array of derived fields
      - `missing_data_fields` string[] — List of the data fields which are missing in the payroll API response
    - `annual_income_summary` AnnualIncomeSummary[] — Annual income summary by years (only for income product)
      - `id` string, required — Unique ID
      - `year` integer, required — Income report year
      - `regular` string, decimal, nullable — Regular salary
      - `bonus` string, decimal, nullable — Bonus
      - `commission` string, decimal, nullable — Commission
      - `overtime` string, decimal, nullable — Overtime pay
      - `other_pay` string, decimal, nullable — All other pays
      - `net_pay` string, decimal, nullable — Net pay
      - `gross_pay` string, decimal, nullable — Gross pay
    - `bank_accounts` BankAccount[] — List of bank accounts linked to the employment (only for income product)
      - `account_number` string, required — Account number
      - `routing_number` string — Routing number
      - `account_name` string, nullable — User friendly account name
      - `account_type` 'C' | 'S' | 'null', nullable — Account type: * `C` - Checking account, * `S` - Savings account,
      - `deposit_type` 'E' | 'P' | 'A' | 'null', nullable — Deposit type: * `E` - Entire paycheck, * `P` - Percentage of the paycheck, * `A` - Fixed amount from the paycheck,
      - `deposit_value` string, decimal, nullable — Deposit value
      - `bank_name` string, nullable — Bank name
    - `w2s` TaxDocumentW2[] — List of W-2 forms linked to the employment (only for income product)
      - `file` string, uri, required — Link to a W2 report file (format is specified in the content-type)
      - `md5sum` string, string, required — MD5 hash value computed based on the file content
      - `year` integer, required — Year
      - `wages` string, decimal, nullable — Wages, tips, other compensation (section 1)
      - `federal_tax` string, decimal, nullable — Federal income tax withheld (section 2)
      - `social_security_wages` string, decimal, nullable — Social security wages (section 3)
      - `social_security_tax` string, decimal, nullable — Social security tax withheld (section 4)
      - `medicare_wages` string, decimal, nullable — Medicare wages (section 5)
      - `medicare_tax` string, decimal, nullable — Medicare tax withheld (section 6)
      - `gross_pay` string, decimal, nullable — Gross pay
    - `id` string, required — Unique ID
    - `is_active` boolean, nullable — Indicates whether the employment is still active
    - `job_title` string, nullable — Employee's job title
    - `job_type` 'F' | 'P' | 'S' | 'D' | 'C' | 'V' | 'null', nullable — Employee's job type: * `F` - Full Time, * `P` - Part Time, * `S` - Seasonal, * `D` - Daily (per diem), * `C` - Contract, * `V` - Volunteer
    - `start_date` string, date, nullable — Employee's hire date
    - `original_hire_date` string, date, nullable — Original hire date
    - `end_date` string, date, nullable — Employee's end date
    - `external_last_updated` string, date, nullable — Indicates the date when employment data was last updated on the Payroll Provider side
    - `dates_from_statements` boolean — Indicates whether or not the Employee's hire and/or end dates were derived from first/last pay statements **(Deprecated)**
    - `derived_fields` string[] — Array of derived fields
    - `missing_data_fields` string[] — List of the data fields which are missing in the payroll API response
    - `manager_name` string, nullable — Supervisor's name
    - `profile` Profile, required — Person's identity information
      - `id` string — ID of the object
      - `created_at` string — Person's identity info was retrieved first time (ISO 8601)
      - `updated_at` string — Person's identity info was retrieved last time (ISO 8601)
      - `first_name` string, required — First name
      - `last_name` string, required — Last name
      - `full_name` string, nullable — Full name
      - `middle_initials` string, nullable — Middle initials
      - `email` string, email, nullable — Email address. Normalized to lowercase.
      - `ssn` string, nullable — Social security number — either the full 9 digits or the last 4 digits, depending on what the data source exposes. Digits only, never formatted with dashes.
      - `date_of_birth` string, date, nullable — Date of birth
      - `home_address` object, nullable — Home address
        - `street` string — Street address as provided by the data source. May contain multiple lines separated by `\n` (address line 1 and line 2).
        - `city` string — City as provided by the data source.
        - `state` string — State or region. For US addresses this is typically a 2-letter state code; some data sources return a full state name, an empty string, or omit the key. Non-US regions are returned as provided.
        - `zip` string — Postal code as provided by the data source. Typically a 5-digit US ZIP code; ZIP+4 (`94105-1804`), 9 digits without a separator, and non-US postal codes also occur.
        - `country` string — 2-letter ISO 3166-1 alpha-2 country code. Defaults to `US` when the data source does not specify a country.
    - `company` Company, required — Company information
      - `name` string, required — Company name. Common legal suffixes (LLC, Inc, Corp, and similar) are stripped during normalization.
      - `address` object, required — Company address
        - `street` string — Street address as provided by the data source. May contain multiple lines separated by `\n` (address line 1 and line 2).
        - `city` string — City as provided by the data source.
        - `state` string — State or region. For US addresses this is typically a 2-letter state code; some data sources return a full state name, an empty string, or omit the key. Non-US regions are returned as provided.
        - `zip` string — Postal code as provided by the data source. Typically a 5-digit US ZIP code; ZIP+4 (`94105-1804`), 9 digits without a separator, and non-US postal codes also occur.
        - `country` string — 2-letter ISO 3166-1 alpha-2 country code. Defaults to `US` when the data source does not specify a country.
      - `phone` string, nullable — Company phone number as provided by the data source. Contains digits and may include `,`, `*`, or `#` for extensions. Usually 10 digits, but a country-code prefix (11-digit `1XXXXXXXXXX`) or an extension can make it longer. Never formatted with punctuation or spaces.
      - `ein` string, nullable — Employer Identification Number (EIN) as provided by the data source. Usually 9 digits with no separator; never formatted with dashes. Some payroll providers supply values that contain letters.

## Other responses

- `400` — HTTP 400 Bad Request
- `401` — HTTP 401 Unauthorized
- `403` — HTTP 403 Forbidden

---

[API](https://skmtc.net/truv/apis/truv-api.md) · [All operations](https://skmtc.net/truv/apis/truv-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/truv/truv-api/versions/b92671dcb52d/schema)