Public beta surface for running qualification checks against a borrower's verified employment and income data. Create a qualification check, retrieve a check result, and list the qualification check sets defined for a tenant. Useful for low-latency knockout decisions (e.g. "minimum gross monthly income") layered on top of full verification reports.
openapi: 3.1.0
info:
title: Truework Qualifications & Tenant Properties API (Beta)
description: >
Public beta surfaces of the Truework API covering Qualification Checks (lightweight
income/employment knockout decisions against a borrower's verified employment data) and
Tenant Properties (provider-defined verification configuration knobs). These endpoints
are in public beta and the schema may evolve.
version: 2023-10-30-beta
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
paths:
/qualification-checks:
post:
operationId: create-new-qualification-check
summary: Create a qualification check request
description: >
Creates a new qualification check and returns a JSON object with the resulting evaluation.
<Warning>
This endpoint is in beta and is subject to change. Please contact
[implementations@truework.com](mailto:implementations@truework.com) for more information before integrating.
</Warning>
tags:
- subpackage_qualificationChecks
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/QualificationChecksPostParametersAccept'
default: application/json
responses:
'201':
description: Qualification Check Evaluation Created.
content:
application/json:
schema:
$ref: '#/components/schemas/QualificationCheckResponseResourceV20231030'
'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/QualificationCheckCreatePostRequestV20231030'
/qualification-checks/{qualification_check_result_id}:
get:
operationId: get-one-qualification-check
summary: Get one qualification check result
description: >
Retrieves a qualification check result by id.
<Warning>
This endpoint is in beta and is subject to change. Please contact
[implementations@truework.com](mailto:implementations@truework.com) for more information before integrating.
</Warning>
tags:
- subpackage_qualificationChecks
parameters:
- name: qualification_check_result_id
in: path
description: Qualification Check Result 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/QualificationChecksQualificationCheckResultIdGetParametersAccept'
default: application/json
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/QualificationCheckResponseResourceV20231030'
'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'
/qualification-check-sets:
get:
operationId: get-all-qualification-check-sets
summary: Get all qualification check sets
description: >
A qualification check set is a ruleset for evaluating income data.
<Warning>
This endpoint is in beta and is subject to change. Please contact
[implementations@truework.com](mailto:implementations@truework.com) for more information before integrating.
</Warning>
tags:
- subpackage_qualificationChecks
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: 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/QualificationCheckSetsGetParametersAccept'
default: application/json
responses:
'200':
description: Qualification Check Sets
content:
application/json:
schema:
$ref: '#/components/schemas/QualificationCheckSetListResourceV20231030'
'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'
/tenant-properties:
post:
operationId: create-new-tenant-property
summary: Create a tenant property
description: >
Creates a new tenant property and returns a JSON object with the resulting property.
<Warning>
This endpoint is in beta and is subject to change. Please contact
[implementations@truework.com](mailto:implementations@truework.com) for more information before integrating.
</Warning>
tags:
- subpackage_tenantProperties
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/TenantPropertiesPostParametersAccept'
default: application/json
responses:
'201':
description: Tenant property successfully created.
content:
application/json:
schema:
$ref: '#/components/schemas/TenantPropertyResourceV20231030'
'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'
requestBody:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/TenantPropertyCreatePostRequestV20231030'
get:
operationId: get-all-tenant-properties
summary: Get all tenant properties
description: Retrieves all tenant properties
tags:
- subpackage_tenantProperties
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: 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/TenantPropertiesGetParametersAccept'
default: application/json
responses:
'200':
description: Tenant Properties
content:
application/json:
schema:
$ref: '#/components/schemas/TenantPropertyListResourceV20231030'
'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'
/tenant-properties/{tenant_property_id}:
get:
operationId: get-one-tenant-property
summary: Get one tenant property
description: Retrieves a tenant property by id.
tags:
- subpackage_tenantProperties
parameters:
- name: tenant_property_id
in: path
description: Tenant Property 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/TenantPropertiesTenantPropertyIdGetParametersAccept'
default: application/json
responses:
'200':
description: Tenant Property
content:
application/json:
schema:
$ref: '#/components/schemas/TenantPropertyResourceV20231030'
'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'
put:
operationId: update-one-tenant-property
summary: Update one tenant property
description: Updates a tenant property.
tags:
- subpackage_tenantProperties
parameters:
- name: tenant_property_id
in: path
description: Tenant Property 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/TenantPropertiesTenantPropertyIdPutParametersAccept'
default: application/json
responses:
'200':
description: Tenant Property
content:
application/json:
schema:
$ref: '#/components/schemas/TenantPropertyResourceV20231030'
'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'
requestBody:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/TenantPropertyUpdatePutRequestV20231030'
servers:
- url: https://api.truework-sandbox.com
- url: https://api.truework.com
components:
schemas:
QualificationChecksPostParametersAccept:
type: string
enum:
- application/json
- application/json; version=2023-10-30
default: application/json
title: QualificationChecksPostParametersAccept
QualificationCheckKind:
type: string
enum:
- applicant
- guarantor
description: The kind of qualification check being requested, either for the applicant or guarantor.
title: QualificationCheckKind
PropertyDetailsInputRent:
oneOf:
- type: number
format: double
- type: string
description: The target rent amount for qualification, expressed in USD
title: PropertyDetailsInputRent
_PropertyDetails-Input:
type: object
properties:
rent:
$ref: '#/components/schemas/PropertyDetailsInputRent'
description: The target rent amount for qualification, expressed in USD
required:
- rent
title: _PropertyDetails-Input
QualificationCheckCreatePostRequestV20231030:
type: object
properties:
kind:
$ref: '#/components/schemas/QualificationCheckKind'
metadata:
type:
- object
- 'null'
additionalProperties:
type: string
description: >-
A single level key-value JSON object that can be used to store custom data on the qualification check; keys
and values must be strings
order_id:
type:
- string
- 'null'
order_ids:
type:
- array
- 'null'
items:
type: string
property_details:
$ref: '#/components/schemas/_PropertyDetails-Input'
qualification_check_set_id:
type: string
report_ids:
type:
- array
- 'null'
items:
type: string
required:
- property_details
- qualification_check_set_id
title: QualificationCheckCreatePostRequestV20231030
_PropertyDetails-Output:
type: object
properties:
rent:
type: string
description: The target rent amount for qualification, expressed in USD
required:
- rent
title: _PropertyDetails-Output
_QualificationCheckSet:
type: object
properties:
applicant_rent_to_income_ratio:
type: string
description: The ratio of the specified rent to the monthly gross income of the applicant.
guarantor_rent_to_income_ratio:
type: string
description: The ratio of the specified rent to the monthly gross income of the guarantor.
id:
type: string
income_multiple:
type:
- string
- 'null'
description: >-
Deprecated. Please use applicant_rent_to_income_ratio. Threshold ratio for target rent to monthly gross
income. Must be greater than 0
name:
type: string
required:
- applicant_rent_to_income_ratio
- guarantor_rent_to_income_ratio
- id
- income_multiple
- name
title: _QualificationCheckSet
QualificationCheckIncomeFidelity:
type: string
enum:
- estimate
- source
description: >-
Whether or not the monthly gross income data was estimated using source data or provided directly from the
source
title: QualificationCheckIncomeFidelity
QualificationCheckOutcome:
type: string
enum:
- qualified
- not_qualified
- not_enough_information
description: The outcome of evaluating a specified set of qualification checks against specified report data
title: QualificationCheckOutcome
_SatisfiedDocumentIncomeRequirement:
type: object
properties:
end_date:
type:
- string
- 'null'
format: date
file_type:
type: string
start_date:
type:
- string
- 'null'
format: date
required:
- end_date
- file_type
- start_date
title: _SatisfiedDocumentIncomeRequirement
_QualificationCheckReportResult:
type: object
properties:
monthly_gross_income:
type:
- string
- 'null'
description: The monthly gross income for a specific report
monthly_gross_income_fidelity:
oneOf:
- $ref: '#/components/schemas/QualificationCheckIncomeFidelity'
- type: 'null'
report_id:
type: string
satisfied_document_income_requirements:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/_SatisfiedDocumentIncomeRequirement'
required:
- monthly_gross_income
- monthly_gross_income_fidelity
- report_id
- satisfied_document_income_requirements
title: _QualificationCheckReportResult
_QualificationCheckResult:
type: object
properties:
monthly_gross_income:
type:
- string
- 'null'
description: The monthly gross income calculated across all requested reports
monthly_gross_income_fidelity:
oneOf:
- $ref: '#/components/schemas/QualificationCheckIncomeFidelity'
- type: 'null'
outcome:
$ref: '#/components/schemas/QualificationCheckOutcome'
rent_to_income_ratio:
type:
- string
- 'null'
description: The ratio of the specified rent to the monthly gross income of the applicant
report_results:
type: array
items:
$ref: '#/components/schemas/_QualificationCheckReportResult'
required:
- monthly_gross_income
# --- truncated at 32 KB (41 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/truework/refs/heads/main/openapi/truework-beta-openapi.yml