openapi: 3.1.0
info:
title: Truework Verifications 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: [email protected]
url: https://www.truework.com/docs
license:
name: Truework Terms of Service
url: https://www.truework.com/legal/terms
paths:
/orders/target-employer:
post:
operationId: create-new-target-employer-verification
summary: Create a target employer order
description: >
Creates a new order and verification. Returns a JSON object representing the newly created order and
verification.
A target employer verification is distinct in that it _requires_ a target employer in the request body for
processing.
## Verification processing
Target employer verifications are processed _asynchronously_: they will be created and returned in the response
body without any [reports](api.yaml/paths/~1verification-requests~1{verification_id}~1report/get). Truework will
then send a webhook when the request has finished processing, and the reports can be retrieved.
This creates a verification request with the following attributes:
- Target employer required
- Is processed asynchronously
- Can be any client-defined combination of Instant, Credentials, and Smart Outreach verification methods
- Returns the verification on a new order object
### Controlling Processing with request config
The request config object allows you to configure how you use Truework by selecting only the verification
methods and features you need.
tags:
- subpackage_orders
parameters:
- 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/OrdersTargetEmployerPostParametersAccept'
default: application/json
responses:
'201':
description: Order Request Created.
content:
application/json:
schema:
$ref: '#/components/schemas/OrderResponseResourceV20231030'
'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'
'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'
requestBody:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/OrderTargetEmployerVerificationRequestV20231030'
/orders/employer-search:
post:
operationId: create-new-order-employer-search-verification
summary: Create an employer search order
description: >
POST requests create both an order and a verification. Returns a JSON object representing the newly created
order and verification.
## Verification processing
Employer search verifications are processed _synchronously_: Truework will attempt to process the verification
during the initial POST request. If successful, the `201` response will include a `reports` key, which will
contain the requested data.
It is recommended to set a timeout on synchronous requests, to account for potential latency when calling our
partners. Synchronous requests generally take only a few seconds to complete, but in rare cases they may take
longer.
This creates a verification request with the following attributes:
- No target company
- Is processed synchronously
- Is Instant verification method only
- Filter employers by one of the following: any-employers, current-employers, previous-employers
- Returns the verification on a new order object
tags:
- subpackage_orders
parameters:
- 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: 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: Include potentially unverified data in the response, including report annotations and unparsed documents.
required: false
schema:
type: boolean
default: false
- 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/OrdersEmployerSearchPostParametersAccept'
default: application/json
responses:
'201':
description: Order and Verification Request Created.
content:
application/json:
schema:
$ref: '#/components/schemas/OrderResponseResourceV20231030'
'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'
'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'
requestBody:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/OrderEmployerSearchVerificationRequestV20231030'
/orders/truework-direct:
post:
operationId: create-new-truework-direct-order
summary: Create a Truework Direct order
description: >-
POST requests create an order with a Truework Direct session token, used for instantiating the Truework.js
widget.
tags:
- subpackage_orders
parameters:
- 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/OrdersTrueworkDirectPostParametersAccept'
default: application/json
responses:
'201':
description: Order Created.
content:
application/json:
schema:
$ref: '#/components/schemas/OrderResponseResourceV20231030'
'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'
'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'
requestBody:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/OrderTrueworkDirectPostRequestV20231030'
/orders/{order_id}:
get:
operationId: get-one-order
summary: Get one order
description: |
Retrieves an order by id.
tags:
- subpackage_orders
parameters:
- name: order_id
in: path
description: Order ID
required: true
schema:
type: string
- name: include_report_annotations
in: query
description: Include potentially unverified data in the response, including report annotations and unparsed documents.
required: false
schema:
type: boolean
default: false
- 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/OrdersOrderIdGetParametersAccept'
default: application/json
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/OrderResponseResourceV20231030'
'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'
/orders:
get:
operationId: get-all-orders
summary: Get all orders
description: An order is a consolidation of multiple verifications.
tags:
- subpackage_orders
parameters:
- name: limit
in: query
description: Limit the number of results returned
required: false
schema:
type: integer
default: 25
- name: offset
in: query
description: Offset the results by page
required: false
schema:
type: integer
default: 0
- name: search_key
in: query
description: Filter by search_key value passed in on Order creation
required: false
schema:
type:
- string
- 'null'
- name: include_report_annotations
in: query
description: Opt-in to including annotations on reports
required: false
schema:
type: boolean
default: false
- name: verification_id
in: query
description: Filter by associated verification_id
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/OrdersGetParametersAccept'
default: application/json
responses:
'200':
description: A list of Orders was successfully retrieved.
content:
application/json:
schema:
$ref: '#/components/schemas/OrderListResponseResourceV20231030'
'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'
'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'
/orders/{order_id}/cancel:
put:
operationId: cancel-an-order
summary: Cancel an order
description: |
Cancels all verification requests on an order, provided each request is not already in a terminal state.
tags:
- subpackage_orders
parameters:
- name: order_id
in: path
description: Order ID
required: true
schema:
type: string
- 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/OrdersOrderIdCancelPutParametersAccept'
default: application/json
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/OrderCancelResponseResourceV20231030'
'400':
description: Bad Request or Order not found
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'
requestBody:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/OrderCancelPutRequestV20231030'
/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'
/orders/{order_id}/events:
get:
operationId: get-order-events
summary: Get order events
description: Returns all events associated with an order.
tags:
- subpackage_orders
parameters:
- name: order_id
in: path
description: Order ID
required: true
schema:
type: string
- name: limit
in: query
description: Limit the number of results returned
required: false
schema:
type: integer
default: 25
- name: offset
in: query
description: Offset the results by page
required: false
schema:
type: integer
default: 0
- 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/OrdersOrderIdEventsGetParametersAccep
# --- truncated at 32 KB (168 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/truework/refs/heads/main/openapi/truework-verifications-orders-openapi.yml