Truework subpackage_reports API

openapi: 3.2.0
info:
  title: Truework Verifications Subpackage Reports API
  description: 'Truework Verifications API for orders, reports, and order events. Submit verification of income and employment (VOIE) orders against a known target employer, run synchronous employer search, kick off a Truework Direct (Truework.js) borrower-driven verification, retrieve completed verification reports, list/cancel orders, and replay order event logs. Current API version is 2023-10-30.

    '
  version: 2023-10-30
  contact:
    name: Truework Implementations
    email: implementations@truework.com
    url: https://www.truework.com/docs
  license:
    name: Truework Terms of Service
    url: https://www.truework.com/legal/terms
servers:
- url: https://api.truework-sandbox.com
- url: https://api.truework.com
tags:
- name: subpackage_reports
paths:
  /reports/{verification_report_id}:
    get:
      operationId: get-report-details
      summary: Get one report
      description: 'Retrieves a report for a given report ID.

        If you don''t have the report id, it is recommended to use the embedded reports key on a completed verification object returned from `GET /orders`.

        You can get the report in PDF format by adding `Accept: application/pdf` to your headers. When testing, please use the generated curl command

        with `--output <PDF filename>` specified.


        <Info>

        Only completed Reports will be returned. Any other request will fail with either 400 or 404, and provide more information as an attached error message.

        </Info>

        '
      tags:
      - subpackage_reports
      parameters:
      - name: verification_report_id
        in: path
        description: Report ID
        required: true
        schema:
          type: string
      - name: include_income_analytics
        in: query
        description: Whether to calculate income analytics for the nested reports in each verification.
        required: false
        schema:
          type: boolean
          default: false
      - name: include_report_annotations
        in: query
        description: Whether to include annotations for the nested reports in each verification.
        required: false
        schema:
          type: boolean
          default: false
      - name: fields
        in: query
        description: Comma-separated names of fields to include in the response. Separate multiple fields with commas, and denote subfields with parentheses. Multiple subfields from the same type can be listed within parentheses. In case of a list, subfields apply to each individual object. If omitted, all fields are included.
        required: false
        schema:
          type:
          - string
          - 'null'
      - name: Authorization
        in: header
        description: 'Bearer tokens conform to the [RFC6750](https://datatracker.ietf.org/doc/html/rfc6750#section-2.1) spec.



          Production API keys (secret keys) are prefixed with `tw_sk_` and sandbox keys are prefixed with `tw_sk_test_`. If your secret key is published, you should rotate your API keys.


          Truework.JS publishable keys are prefixed with `tw_pk_` and `tw_pk_test` respectively.



          **Examples**

          - For Authorization Headers: `Authorization: Bearer tw_sk_test_e508eb797edb95ade85284bcb54dd49ed45db1be`

          - For the "try it now" `token` field, input only the token itself, omitting `Bearer `.'
        required: true
        schema:
          type: string
      - name: Accept
        in: header
        description: Specify the content type and version that the API should use. It's recommended to include this to avoid breaking changes.
        required: false
        schema:
          $ref: '#/components/schemas/ReportsVerificationReportIdGetParametersAccept'
          default: application/json
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderVerificationReportResourceV20231030'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: The request's authorization is missing, invalid, or expired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '406':
          description: An invalid API version was requested
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error406'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error429'
        '451':
          description: Frozen SSN
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error451'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
        '501':
          description: Not Implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error501'
components:
  schemas:
    EligibilityProviderOutputWrapperV20231030:
      type: object
      properties:
        canonical_value:
          $ref: '#/components/schemas/EligibilityProviderOutputWrapperV20231030CanonicalValue'
          description: A limited enum representation of the value, which will not be extended without a version bump.
        raw_value:
          type: string
          description: An unlimited string representation of the value, which may provide more detail when the canonical value is "other".
      required:
      - canonical_value
      - raw_value
      title: EligibilityProviderOutputWrapperV20231030
    SalaryV20231030:
      type: object
      properties:
        hours_per_week:
          type:
          - string
          - 'null'
        pay_frequency:
          oneOf:
          - $ref: '#/components/schemas/PayFrequencyOutputWrapperV20231030'
          - type: 'null'
          description: The frequency by which the employee is paid.
        pay_rate:
          oneOf:
          - $ref: '#/components/schemas/PayRateV20231030'
          - type: 'null'
          description: Describes the amount and unit that determine the employees pay.
        reduced_covid:
          $ref: '#/components/schemas/ReducedCovidVMinimumVersion'
      required:
      - hours_per_week
      - pay_frequency
      - pay_rate
      - reduced_covid
      title: SalaryV20231030
    _AnnualizedIncome:
      type: object
      properties:
        base_amount:
          oneOf:
          - $ref: '#/components/schemas/MoneyAmountVMinimumVersion'
          - type: 'null'
          description: Represents annualized income for recurring income, like salary. In rare cases due to data quality issues, gross amount is returned without base amount or vice versa.
        gross_amount:
          oneOf:
          - $ref: '#/components/schemas/MoneyAmountVMinimumVersion'
          - type: 'null'
          description: Represents base annualized income plus variable income sources. In rare cases due to data quality issues, gross amount is returned without base amount or vice versa.
        short_employment_warning:
          type: boolean
          description: True if the employee recently started at this position, which could impact annualized income accuracy.
        stale_data_warning:
          type: boolean
          description: True if the data on this report is not fresh, which could impact annualized income accuracy.
        variable_income_warning:
          type: boolean
          description: True if the employees income has high variability, which could impact annualized income accuracy.
      required:
      - base_amount
      - gross_amount
      - short_employment_warning
      - stale_data_warning
      - variable_income_warning
      title: _AnnualizedIncome
    CompletedByMethodOutputWrapperV20231030:
      type: object
      properties:
        canonical_value:
          $ref: '#/components/schemas/CompletedByMethodOutputWrapperV20231030CanonicalValue'
          description: A limited enum representation of the value, which will not be extended without a version bump.
        raw_value:
          type: string
          description: An unlimited string representation of the value, which may provide more detail when the canonical value is "other".
      required:
      - canonical_value
      - raw_value
      title: CompletedByMethodOutputWrapperV20231030
    EmployeeStatusOutputWrapperV20231030CanonicalValue:
      type: string
      enum:
      - active
      - inactive
      - unknown
      - furloughed-covid
      - non-employee
      - other
      description: 'There are five employment statuses available on the `status` field in

        `Employee`:


        | VALUE            | DESCRIPTION                                                         | VERSION INTRODUCED | OLDER VERSION VALUE |

        | ---------------- | ------------------------------------------------------------------- | ------------------ | ------------------- |

        | active           | The employee is currently employed and working for this employer    |                    |                     |

        | inactive         | The employee is not employed at this employer anymore               |                    |                     |

        | unknown          | Truework could not determine the employment status of this employee |                    |                     |

        | furloughed-covid | The employee was furloughed due to COVID-19                         | `2020-12-07`       | inactive            |

        | non-employee     | Truework could not find record of this employee                     | `2020-12-07`       | unknown             |

        | other | No other value describes the employee''s status | `2022-08-01` | N/A |'
      title: EmployeeStatusOutputWrapperV20231030CanonicalValue
    CompletedByMethodOutputWrapperV20231030CanonicalValue:
      type: string
      enum:
      - instant
      - credentials
      - smart-outreach
      - third-party-providers
      - other
      description: A limited enum representation of the value, which will not be extended without a version bump.
      title: CompletedByMethodOutputWrapperV20231030CanonicalValue
    DetectionOutcomeWrapperCanonicalValue:
      type: string
      enum:
      - passed
      - failed
      - not-run
      - other
      description: 'The outcome of the detection rule.


        | VALUE | DESCRIPTION |

        | ----- | ----------- |

        | passed | The detection rule passed. |

        | failed | The detection rule failed. |

        | not-run | The detection rule was not run. |

        | other | Another outcome occurred. |'
      title: DetectionOutcomeWrapperCanonicalValue
    PayUnitOutputWrapperV20231030CanonicalValue:
      type: string
      enum:
      - annually
      - daily
      - semiweekly
      - monthly
      - weekly
      - biweekly
      - bimonthly
      - semimonthly
      - quarterly
      - semiannually
      - thirteen-monthly
      - fourteen-monthly
      - hourly
      - variable
      - other
      description: A limited enum representation of the value, which will not be extended without a version bump.
      title: PayUnitOutputWrapperV20231030CanonicalValue
    Error406:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/Error'
      required:
      - error
      title: Error406
    Error400:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/_InvalidRequestError'
      required:
      - error
      title: Error400
    DisputeV20231030:
      type: object
      properties:
        created:
          type: string
          format: date-time
        description:
          type:
          - string
          - 'null'
          description: Description of dispute
        id:
          type: string
          description: ID for this dispute in Truework
        reference_id:
          type:
          - string
          - 'null'
          description: ID for this dispute to be displayed and referenced outside of this API
      required:
      - created
      - description
      - id
      - reference_id
      title: DisputeV20231030
    _EmployeeAnnotation:
      type: object
      properties:
        positions:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/_PositionAnnotation'
        salary:
          oneOf:
          - $ref: '#/components/schemas/_SalaryAnnotation'
          - type: 'null'
        status:
          oneOf:
          - $ref: '#/components/schemas/EmployeeStatusOutputWrapperV20231030'
          - type: 'null'
        status_detail:
          oneOf:
          - $ref: '#/components/schemas/EmployeeStatusDetailOutputWrapperV20231030'
          - type: 'null'
      required:
      - positions
      - salary
      - status
      - status_detail
      title: _EmployeeAnnotation
    EligibilityTypeOutputWrapperV20231030CanonicalValue:
      type: string
      enum:
      - d1c
      - other
      description: A limited enum representation of the value, which will not be extended without a version bump.
      title: EligibilityTypeOutputWrapperV20231030CanonicalValue
    EmployeeStatusDetailOutputWrapperV20231030:
      type: object
      properties:
        canonical_value:
          $ref: '#/components/schemas/EmployeeStatusDetailOutputWrapperV20231030CanonicalValue'
          description: 'The `status_detail` provides more granular information for some `status` values:


            | VALUE              | DESCRIPTION                                                         | `Status`         |

            | ------------------ | ------------------------------------------------------------------- | ---------------- |

            | active             | The employee is currently employed and working for this employer    | active           |

            | int-assignment     | The employee is on international assignment                         | active           |

            | casual             | The employee is employed casually                                   | active           |

            | long-term-dis      | The employee is on long term disability                             | active           |

            | sick-leave         | The employee is on sick leave                                       | active           |

            | surviving-spouse   | The employee is a surviving spouse                                  | inactive         |

            | inactive           | The employee is not employed at this employer anymore               | inactive         |

            | on-leave           | The employee is on leave                                            | active           |

            | multiple-positions | The employee has multiple active positions                          | active           |

            | new-employee       | The employee is new                                                 | active           |

            | lay-off            | The employee was laid off                                           | inactive         |

            | part-time          | The employee is currently employed on a part time basis             | active           |

            | retired            | The employee is retired                                             | inactive         |

            | separated          | The employee is separated                                           | inactive         |

            | season             | The employee is seasonal                                            | active           |

            | temporary          | The employee is temporary                                           | active           |

            | intern             | The employee is an intern                                           | active           |

            | transferred        | The employee has been transferred                                   | active           |

            | deceased           | The employee is deceased                                            | inactive         |

            | severed-pay        | The employee has been severed with pay                              | inactive         |

            | on-sabbatical      | The employee is on sabbatical                                       | active           |

            | divested           | The employee is part of a divested population                       | active           |

            | temp-inactive      | The employee is temporarily inactive                                | inactive         |

            | full-time          | The employee is full time                                           | active           |

            | non-emp-ben        | The employee is a non employee beneficiary                          | inactive         |

            | not-assignment     | The employee is not currently on assignment                         | inactive         |

            | not-payroll        | The employee is not currently on payroll                            | inactive         |

            | active-as-needed   | The employee is active as needed                                    | active           |

            | unknown            | Truework could not determine the employment status of this employee | unknown          |

            | furloughed-covid   | The employee was furloughed due to COVID-19                         | furloughed-covid |

            | non-employee       | Truework could not find record of this employee                     | non-employee     |

            | other              | No other value exemplifies Verification Status Detail               | other            |'
        raw_value:
          type: string
          description: An unlimited string representation of the value, which may provide more detail when the canonical value is "other".
      required:
      - canonical_value
      - raw_value
      title: EmployeeStatusDetailOutputWrapperV20231030
    FinancialInstitutionIncomeStreamPeriodV20231030:
      type: object
      properties:
        amount:
          type:
          - number
          - 'null'
          format: double
        amount_duration:
          type: string
        amount_type:
          type: string
        estimated_gross_income:
          oneOf:
          - $ref: '#/components/schemas/GrossIncomeCalculationResultV20231030'
          - type: 'null'
        id:
          type: string
        start_day:
          type: string
          format: date
      required:
      - amount
      - amount_duration
      - amount_type
      - estimated_gross_income
      - id
      - start_day
      title: FinancialInstitutionIncomeStreamPeriodV20231030
    _GovernmentId:
      type: object
      properties:
        id:
          type: string
        type:
          $ref: '#/components/schemas/GovernmentIdTypeOutputWrapperV20231030'
      required:
      - id
      - type
      title: _GovernmentId
    _SalaryAnnotation:
      type: object
      properties:
        pay_rate:
          oneOf:
          - $ref: '#/components/schemas/PayRateV20231030'
          - type: 'null'
      required:
      - pay_rate
      title: _SalaryAnnotation
    ReducedCovidVMinimumVersion:
      type: string
      enum:
      - 'yes'
      - 'no'
      - unknown
      title: ReducedCovidVMinimumVersion
    PayUnitOutputWrapperV20231030:
      type: object
      properties:
        canonical_value:
          $ref: '#/components/schemas/PayUnitOutputWrapperV20231030CanonicalValue'
          description: A limited enum representation of the value, which will not be extended without a version bump.
        raw_value:
          type: string
          description: An unlimited string representation of the value, which may provide more detail when the canonical value is "other".
      required:
      - canonical_value
      - raw_value
      title: PayUnitOutputWrapperV20231030
    DocumentDetection:
      type: object
      properties:
        count:
          type: integer
        outcome:
          $ref: '#/components/schemas/DetectionOutcomeWrapper'
        type:
          $ref: '#/components/schemas/DetectionTypeWrapper'
      required:
      - count
      - outcome
      - type
      title: DocumentDetection
    GovernmentIdTypeOutputWrapperV20231030:
      type: object
      properties:
        canonical_value:
          $ref: '#/components/schemas/GovernmentIdTypeOutputWrapperV20231030CanonicalValue'
          description: A limited enum representation of the value, which will not be extended without a version bump.
        raw_value:
          type: string
          description: An unlimited string representation of the value, which may provide more detail when the canonical value is "other".
      required:
      - canonical_value
      - raw_value
      title: GovernmentIdTypeOutputWrapperV20231030
    DetectionTypeWrapper:
      type: object
      properties:
        canonical_value:
          $ref: '#/components/schemas/DetectionTypeWrapperCanonicalValue'
          description: 'The type of detection that was found on the document.


            | VALUE | DESCRIPTION |

            | ----- | ----------- |

            | ssn-mismatch | The SSN on the document does not match the SSN on the request. |

            | employer-name-mismatch | The employer name on the document may not match the employer name on the request. |

            | page-edited | The form may have been created by a recognized software package. |

            | other-edits | The form may have been edited with a recognized software package. |

            | online-generated-paystub | The pay stub format may match a template from sites known to create paystubs for a fee. |

            | earnings-edits | The listed earnings may have been edited. |

            | deductions-edits | Current or YTD deductions (including taxes) may have been edited. |

            | pay-frequency-edits | Pay frequency may have been edited. |

            | dollar-amount-edits | One or more of the following dollar amounts may have been changed: Beginning balance, Ending balance, Total deposits, Total withdrawals, Daily balance, Individual amounts, Ledger balances. |

            | employee-taxpayer-id-edits | The employee''s social security number may have been edited. |

            | employee-details-edits | The employee''s marital status may have been edited. |

            | employee-name-edits | The employee''s name may have been edited. |

            | employer-name-edits | The employer’s name may have been edited. |

            | employer-address-edits | The employer’s address may have been edited. |

            | date-edits | One or more of the following dates may have been edited (hire date, pay period, period start date, period end date). |

            | misaligned-text | The field or text may not match the expected alignment compared to the rest of the document. |

            | other | Something else was detected. |'
        raw_value:
          type: string
          description: An unlimited string representation of the value, which may provide more detail when the canonical value is "other".
      required:
      - canonical_value
      - raw_value
      title: DetectionTypeWrapper
    GrossIncomeCalculationResultV20231030:
      type: object
      properties:
        average_monthly_net_income:
          type:
          - number
          - 'null'
          format: double
        estimated_gross_annual:
          type:
          - number
          - 'null'
          format: double
        net_annual:
          type:
          - number
          - 'null'
          format: double
      required:
      - average_monthly_net_income
      - estimated_gross_annual
      - net_annual
      title: GrossIncomeCalculationResultV20231030
    EmployeeStatusOutputWrapperV20231030:
      type: object
      properties:
        canonical_value:
          $ref: '#/components/schemas/EmployeeStatusOutputWrapperV20231030CanonicalValue'
          description: 'There are five employment statuses available on the `status` field in

            `Employee`:


            | VALUE            | DESCRIPTION                                                         | VERSION INTRODUCED | OLDER VERSION VALUE |

            | ---------------- | ------------------------------------------------------------------- | ------------------ | ------------------- |

            | active           | The employee is currently employed and working for this employer    |                    |                     |

            | inactive         | The employee is not employed at this employer anymore               |                    |                     |

            | unknown          | Truework could not determine the employment status of this employee |                    |                     |

            | furloughed-covid | The employee was furloughed due to COVID-19                         | `2020-12-07`       | inactive            |

            | non-employee     | Truework could not find record of this employee                     | `2020-12-07`       | unknown             |

            | other | No other value describes the employee''s status | `2022-08-01` | N/A |'
        raw_value:
          type: string
          description: An unlimited string representation of the value, which may provide more detail when the canonical value is "other".
      required:
      - canonical_value
      - raw_value
      title: EmployeeStatusOutputWrapperV20231030
    _EmployerAnnotation:
      type: object
      properties:
        email:
          type:
          - string
          - 'null'
          format: email
        name:
          type:
          - string
          - 'null'
        phone_number:
          type:
          - string
          - 'null'
      required:
      - email
      - name
      - phone_number
      title: _EmployerAnnotation
    ReportIncomeAnalyticsV20231030:
      type: object
      properties:
        annualized_income:
          oneOf:
          - $ref: '#/components/schemas/_AnnualizedIncome'
          - type: 'null'
        income_volatility:
          oneOf:
          - $ref: '#/components/schemas/_IncomeVolatility'
          - type: 'null'
      required:
      - annualized_income
      - income_volatility
      title: ReportIncomeAnalyticsV20231030
    EmployeeV20231030:
      type: object
      properties:
        address:
          oneOf:
          - $ref: '#/components/schemas/AddressV20220801-Output'
          - type: 'null'
        earnings:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/EarningsV20231030'
        email:
          type:
          - string
          - 'null'
          format: email
        first_name:
          type:
          - string
          - 'null'
        hired_date:
          type:
          - string
          - 'null'
          format: date
          description: This is the most recent hiring date of the employee. If the employee has been rehired, this date will be updated to the most recent hiring date.
        last_name:
          type:
          - string
          - 'null'
        on_leave_date:
          type:
          - string
          - 'null'
          format: date
        original_hired_date:
          type:
          - string
          - 'null'
          format: date
          description: This is the original hiring date of the employee. If the employee has been rehired, this date will not change.
        positions:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/PositionV20231030'
        salary:
          oneOf:
          - $ref: '#/components/schemas/SalaryV20231030'
          - type: 'null'
        social_security_number:
          type:
          - string
          - 'null'
          description: The employee's obfuscated social security number
        status:
          oneOf:
          - $ref: '#/components/schemas/EmployeeStatusOutputWrapperV20231030'
          - type: 'null'
        status_detail:
          oneOf:
          - $ref: '#/components/schemas/EmployeeStatusDetailOutputWrapperV20231030'
          - type: 'null'
        termination_date:
          type:
          - string
          - 'null'
          format: date
      required:
      - address
      - earnings
      - email
      - first_name
      - hired_date
      - last_name
      - on_leave_date
      - original_hired_date
      - positions
      - salary
      - social_security_number
      - status
      - status_detail
      - termination_date
      title: EmployeeV20231030
    RespondentV20231030:
      type: object
      properties:
        email:
          type:
          - string
          - 'null'
        full_name:
          type:
          - string
          - 'null'
        title:
          type:
          - string
          - 'null'
      required:
      - email
      - full_name
      - title
      title: RespondentV20231030
    _IncomeVolatility:
      type: object
      properties:
        gross_income_volatility:
          type:
          - string
          - 'null'
          description: Coefficient of variation of the aggregated per pay period gross earnings for a given list of paystubs.
      required:
      - gross_income_volatility
      title: _IncomeVolatility
    PaystubV20231030:
      type: object
      properties:
        base:
          type:
          - string
          - 'null'
          description: Pre-deduction base pay
        bonus:
          type:
          - string
          - 'null'
          description: Pre-deduction bonus pay
        commission:
          type:
          - string
          - 'null'
          description: Pre-deduction commission pay
        gross:
          type:
          - string
          - 'null'
          description: Total pre-deduction earnings for this pay period
        id:
          type: string
          description: ID for this paystub in Truework
        net:
          type:
          - string
          - 'null'
          description: Total post-deduction earnings for this pay period
        other:
          type:
          - string
          - 'null'
          description: Pre-deduction other pay
        overtime:
          type:
          - string
          - 'null'
          description: Pre-deduction overtime pay
        pay_date:
          type:
          - string
          - 'null'
          format: date
          description: Date of paycheck delivery
        pay_period_end_date:
          type:
          - string
          - 'null'
          format: date
          description: Last day of pay period
        pay_period_hours:
          type:
          - string
          - 'null'
          description: Hours worked in this pay period
        pay_period_start_date:
          type:
          - string
          - 'null'
          format: date
          description: First day of pay period
        reference_id:
          type:
          - string
          - 'null'
          description: ID for this paystub from the payroll provider
      required:
      - base
      - bonus
      - commission
      - gross
      - id
      - net
      - other
      - overtime
      - pay_date
      - pay_period_end_date
      - pay_period_hours
      - pay_period_start_date
      - reference_id
      title: PaystubV20231030
    PositionV20231030:
      type: object
      properties:
        employment_type:
          oneOf:
          - $ref: '#/components/schemas/EmploymentTypeOutputWrapperV20231030'
          - type: 'null'
        end_date:
          type:
          - string
          - 'null'
          format: date
        start_date:
          type:
          - string
          - 'null'
          format: date
        

# --- truncated at 32 KB (60 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/truework/refs/heads/main/openapi/truework-subpackage-reports-api-openapi.yml