Using the APIVersioning

Current API version (2023-10-30)

This is the latest version of the Truework API.

The API response resource hierarchy has been revised such that orders will be introduced as the highest-level resource, acting as a container for Verifications. Verification management (create, read, cancel, reverify, etc.) will move from the verification top-level resource (/verification-requests) to the order top-level resource (/orders). Verification reports will have their own top-level resource (/reports) for read requests. Verification creation will be split into two modes: one for handling employer search requests (no target company), one for handling target company requests. The verification response objects for each mode will be nested inside of a newly created order.

Income analytics

Income analytics is a collection of data points derived from verified current and historical income data that allows lenders to make more precise underwriting and pricing decisions. This feature is available for endpoints that have an include_income_analytics query field on the request object.

Unverified Information and report annotations

Unverified information represents data that has been added by a verifier or applicant to supplement a verification, but has not been verified. If this information is added to a verification with reports, the information is stored as report annotations on the report. This information is now available for endpoints that have an include_report_annotations query field in the request object.

The order top-level resource will have 4 different “modes”, each representing a different endpoint: employer-search, target-employer, truework-direct, and reverification.

employer-search order mode

  • New endpoint: /orders/employer-search
  • Supersedes verification creation requests to /verification-requests (i.e. “Create a Verification”) and has the following attributes:
  • No target company.
  • Is executed synchronously (results will come back from the POST request).
  • instant is the only verification method.
  • date_of_birth is a required attribute for targets.
  • Filters employers by one of the following: all-employers, current-employer, previous-employers via a config field on the request.
  • Returns one verification resource for each employer found. If no employers are found, returns zero verification resources.

target-employer order mode

  • New endpoint: /orders/target-employer
  • Supersedes verification creation requests to /verification-requests (i.e. “Create a Verification”) and has the following attributes:
  • A target company is required (i.e. the equivalent of employer-filter = target-company on the existing endpoint).
  • Is executed asynchronously (you will be notified via webhook when results are available).
  • Activates specific verification methods (i.e. instant, credentials, etc.) via a config field on the request.
  • Returns one verification resource.

reverification order mode

  • New endpoint: /orders/reverification
  • Supersedes requests to existing /verification-requests/{verification_request_id}/reverify (i.e. “Reverify a Verification”) endpoint.
  • Very similar to existing reverification functionality.
  • Returns a verification resource on a new order object (matches the existing order response schema with minor changes).

truework-direct order mode

  • New endpoint: /orders/truework-direct
  • Creates an order and a Truework Direct session for teams with Truework Direct enabled.
  • Supersedes requests to existing /credentials/session (i.e. “Create a Credentials Session”) endpoint for teams without Truework Direct enabled.

Endpoint modifications and replacements

  • /orders/{order_id}/cancel
  • Cancels all verifications associated with an order.
  • Supersedes /verification-requests/{verification_request_id}/cancel
  • /reports/{verification_report_id}
  • Detail endpoint for reading reports.
  • Supersedes /verification-requests/{verification_request_id}/reports/{verification_report_id}
  • /orders/{order_id}
  • Detail endpoint for reading orders.
  • Supersedes /verification-requests/{verification_request_id}
  • /orders
  • List endpoint for reading all orders.
  • Supersedes /verification-requests

Verification resources have the following changes for all endpoints

  • The price field has been removed.
  • The applicant_documents field has been added to represent applicant-uploaded information.
  • The unverified_information field is now available for endpoints that have an include_report_annotations query field on the request object.

Verification report resources have the following changes for all endpoints

  • The pricing_tier field has been replaced by completed_by_method.
  • The pricing_tier_detail field has been replaced by completed_by_source.
  • The du_reference_id and d1c_eligible fields have been replaced by eligibilities.
  • The applicant_documents field has been added to represent applicant-uploaded information.
  • The annotations field is now available for endpoints that have an include_report_annotations query field in the request object.
  • The income_analytics field is now available for endpoints that have an include_income_analytics query field on the request object.