---
title: "Retrieve an income and employment report for a link"
method: GET
path: "/v1/links/{link_id}/income/report/"
tags: ["Reports"]
---

# Retrieve an income and employment report for a link

`GET /v1/links/{link_id}/income/report/`

## Request

- Base URL: `https://prod.truv.com`
- URL: `https://prod.truv.com/v1/links/{link_id}/income/report/`
- Auth: API key in header `X-Access-Client-Id` and API key in header `X-Access-Secret`

The endpoint returns the VOIE report for a link

## Query parameters

- `show_fraud_reasons` boolean

## Response `200`

- IncomeCheck: Data for the income verification
  - `id` string, required: Unique ID
  - `status` string, required: [Request status](https://docs.truv.com/reference/task-livecycle)
  - `finished_at` string: Time when report was finished
  - `completed_at` string, required: Time when report was completed **(Deprecated, invalid datetime format)**
  - `access_token` string, required: Access token for a Link to payroll provider
  - `tracking_info` string, nullable, required: Any information passed to the Truv Bridge from a partner
  - `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
  - `fraud_reasons` FraudReason[]: Findings recorded for this link and its tasks. Included only when `show_fraud_reasons=true`. An empty array means no findings are available for this response.
    - `code` 'editing_software_detected' | 'screenshot' | 'design_software_detected' | 'document_from_online_generator' | 'office_software_detected' | 'scanned_document' | 'suspicious_producer' | 'blocked_text_content' | 'document_type_mismatch' | 'ai_generated_content' | 'invalid_content_credentials' | 'malware_detected' | 'modified_before_creation_date' | 'future_date' | 'modified_after_creation' | 'anomalous_pdf_structure' | 'invalid_date' | 'has_only_images' | 'insufficient_text' | 'content_tampering_suspected' | 'content_diff_between_versions' | 'ssn_mismatch_between_documents' | 'ssn_mismatch_with_applicant' | 'inconsistent_payroll_taxes', required: Machine-readable identifier for the type of finding.
    - `message` string, required: Human-readable explanation of the finding.
    - `severity` 'high' | 'medium' | 'low', required: Severity assigned to the finding. This value is not a confidence score. Use the task status to determine the current processing outcome. `high` - finding classified as fraud, `medium` - finding classified as suspicious, `low` - document-quality or validation finding, not a fraud finding.
    - `document_ids` string[], required: IDs of the documents associated with the finding. Empty when the finding does not refer to a specific document. These are Documents API IDs, which differ from Collections API `document_id` values.
    - `uploaded_file_ids` string[], required: IDs of the original files uploaded through a document collection. Empty when no associated collection upload is available. One uploaded file may contain multiple recognized documents.
    - `details` object, required: Additional information about the finding. Available fields depend on the reason code.
    - `task_id` string, nullable, required: ID of the task associated with the finding. `null` if the finding was recorded directly on the link without an associated task.
    - `created_at` string, date-time, required: Date and time the finding was recorded, in ISO 8601 format.
  - `refresh_status` string, required: Status of the most recent refresh task
  - `employments` EmploymentIncome[], required: List of employments received from a payroll provider
    - `income` string, decimal, nullable: Income amount not including commission or bonuses
    - `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
    - `pay_rate` string, decimal, nullable: Payment rate per pay cycle
    - `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
    - `statements` Statement[]: List of paystubs received from a payroll provider
      - `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
      - `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
      - `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
      - `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.
  - `pdf_report` string, uri: Verification report in PDF format
  - `provider` string, required: Payroll provider name
  - `data_source` 'payroll' | 'docs' | 'financial_accounts': Source of data: crawler - payroll provider parsing, docs - user uploaded documents

## Other responses

- `401`: HTTP 401 Unauthorized
- `403`: HTTP 403 Forbidden
- `404`: HTTP 404 Not Found

## Changes

- **2026-10-30** `64de38c55f45`: 2 info
  - added the new optional `query` request parameter `show_fraud_reasons`
  - added the optional property `fraud_reasons` to the response with the `200` status
- **2026-08-08** `6542a8962887`: 1 info
  - added the non-success response with the status `404`
- **2026-07-27** `f7c013875516`: 1 warning, 37 info
  - added the new `C` enum value to the `employments/items/statements/items/basis_of_pay` response property for the response status `200`
  - the `employments/items/annual_income_summary/items/bonus` response's property pattern `^-?\d{1,10}\.\d{2}$` was added for the status `200`
  - the `employments/items/annual_income_summary/items/commission` response's property pattern `^-?\d{1,10}\.\d{2}$` was added for the status `200`
  - the `employments/items/annual_income_summary/items/gross_pay` response's property pattern `^-?\d{1,10}\.\d{2}$` was added for the status `200`
  - …34 more
- **2026-07-26** `e58688835e25`: 13 breaking, 3 warning
  - the response property `employments/items/end_date` became nullable for the status `200`
  - the response property `employments/items/external_last_updated` became nullable for the status `200`
  - the response property `employments/items/income` became nullable for the status `200`
  - the response property `employments/items/income_unit` became nullable for the status `200`
  - …12 more

[Operation history](https://skmtc.dev/truv/apis/truv-api/changes/v1/links/:link_id/income/report/get.md)

---

[API](https://skmtc.dev/truv/apis/truv-api.md) - [All operations](https://skmtc.dev/truv/apis/truv-api/llms.txt) - [OpenAPI document](https://skmtc.dev/truv/apis/truv-api/revisions/e20fd88e9371?raw)