For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Truework.comAPI StatusGet your API key
HomeGuidesAPI referenceHelp
HomeGuidesAPI referenceHelp
    • Introduction
  • Using the API
    • Authentication
    • Versioning
    • Webhooks
    • Sandbox environment
    • Monitoring
    • Limits
  • Verification orders & reports
    • POSTCreate a target employer order
    • POSTCreate an employer search order
    • POSTCreate a Truework Direct order
    • GETGet one order
    • GETGet all orders
    • PUTCancel an order
    • GETGet one report
    • GETGet order events
    • POSTReverify a report
  • Public beta APIs
  • Previous API versions
    • API version 2022-08-01
    • API version 2020-12-07
      • POSTCreate a Credentials Session
      • POSTCreate a Verification
      • GETGet All Verifications
      • GETGet One Verification
      • PUTReverify a Verification
      • PUTCancel a Verification
      • GETGet One Report
    • API version 2019-10-15
LogoLogo
Truework.comAPI StatusGet your API key
Previous API versionsAPI version 2020-12-07

Get One Verification

Deprecated
GET
/verification-requests/:verification_request_id
GET
/verification-requests/:verification_request_id
$curl https://api.truework-sandbox.com/verification-requests/verification_request_id \
>     -H "Authorization: Bearer <token>"
1{
2  "additional_information": "string",
3  "cancellation_details": "string",
4  "cancellation_reason": "immediate",
5  "created": "2021-12-20T18:50:20.291247Z",
6  "date_of_completion": "2021-12-20T18:50:20.291247Z",
7  "documents": [
8    {
9      "filename": "test.pdf"
10    }
11  ],
12  "id": "AAAAAAAAAosABwGqF1AUKAH0-puth1tCzLNar3Jyb4bx3wdVKU99XC26",
13  "loan_id": "string",
14  "metadata": {},
15  "permissible_purpose": "child-support",
16  "price": {
17    "amount": "34.95",
18    "currency": "USD"
19  },
20  "reports": [
21    {
22      "additional_notes": "string",
23      "created": "2021-12-20T18:50:20.291247Z",
24      "current_as_of": "2021-12-20",
25      "d1c_eligible": true,
26      "disputes": [
27        {
28          "created": "2021-12-20T18:50:20.291247Z",
29          "description": "Employee Title",
30          "id": "AAAAAAAAAL8AElevkrw2n2vI8ScqGJEf50Lfg4W9LiQXwi-KSmg7DH0P",
31          "reference_id": "d75346a0-a747-4907-a506-639ea436f2b0"
32        }
33      ],
34      "du_reference_id": "string",
35      "employee": {
36        "earnings": [
37          {
38            "base": "35000.00",
39            "bonus": "0.00",
40            "commission": "100.25",
41            "other": "0.00",
42            "overtime": "200.00",
43            "termination": false,
44            "total": "35300.25",
45            "year": "2020"
46          }
47        ],
48        "email": "string",
49        "first_name": "Jane",
50        "hired_date": "2023-01-15",
51        "last_name": "Doe",
52        "on_leave_date": "2023-01-15",
53        "positions": [
54          {
55            "employment_type": "regular-full-time",
56            "end_date": "2023-01-15",
57            "start_date": "2023-01-15",
58            "title": "Software Engineer"
59          }
60        ],
61        "salary": {
62          "gross_pay": "string",
63          "hours_per_week": "40",
64          "months_per_year": "12",
65          "pay_frequency": "biweekly",
66          "reduced_covid": "yes"
67        },
68        "social_security_number": "***-**-0000",
69        "status": "active",
70        "status_detail": "active",
71        "termination_date": "2023-01-15"
72      },
73      "employer": {
74        "address": "string",
75        "government_ids": [
76          {
77            "id": "123456789",
78            "type": "us-fein"
79          }
80        ],
81        "name": "string"
82      },
83      "id": "AAAAAAAADU8ACy03lGitY_ocCMCcgproUq8Gt4r37MM6GbyX2-DxWM3Y",
84      "income_analytics": {
85        "annualized_income": {
86          "amount": {
87            "amount": "34.95",
88            "currency": "USD"
89          },
90          "base_amount": {
91            "amount": "34.95",
92            "currency": "USD"
93          },
94          "gross_amount": {
95            "amount": "34.95",
96            "currency": "USD"
97          },
98          "short_employment_warning": true,
99          "stale_data_warning": true,
100          "variable_income_warning": true
101        },
102        "income_volatility": {
103          "gross_income_volatility": "string"
104        }
105      },
106      "paid_through_date": "2023-01-15",
107      "paystubs": [
108        {
109          "base": "7000.00",
110          "bonus": "1000.00",
111          "commission": "0.00",
112          "gross": "8000.00",
113          "id": "AAAAAAAAAmEADp7bmZJNhm4Kr5FM_ty5A_JX-Rxh04GSIHwmIRyp6Xss",
114          "net": "5500.00",
115          "other": "0.00",
116          "overtime": "0.00",
117          "pay_date": "2023-01-15",
118          "pay_period_end_date": "2023-01-15",
119          "pay_period_hours": "86.67",
120          "pay_period_start_date": "2023-01-15",
121          "reference_id": "6894632654"
122        }
123      ],
124      "pricing_tier": "instant",
125      "respondent": {
126        "email": "string",
127        "full_name": "string",
128        "title": "string"
129      },
130      "verification_request": {
131        "created": "2021-12-20T18:50:20.291247Z",
132        "id": "AAAAAAAAEboABwQhKv1_pWO7MWtZs28ksPTH0uSt6GffsoIJPj7e69P1",
133        "type": "employment"
134      }
135    }
136  ],
137  "request_parameters": {
138    "employer_filter": "target-employer",
139    "verification_methods": {
140      "credentials": {
141        "enabled": true
142      },
143      "instant": {
144        "enabled": true
145      },
146      "smart_outreach": {
147        "enabled": true
148      }
149    }
150  },
151  "reseller_originating_party": {
152    "originating_party": "string",
153    "permissible_purpose": "child-support",
154    "use_case": "mortgage"
155  },
156  "state": "pending-approval",
157  "target": {
158    "company": {
159      "address": "string",
160      "city": "string",
161      "id": 1,
162      "name": "Example Inc.",
163      "phone_number": "string",
164      "state": "string",
165      "zip_code": "string"
166    },
167    "contact_email": "string",
168    "date_of_birth": "2023-01-15",
169    "first_name": "Jane",
170    "last_name": "Doe",
171    "phone_number": "string",
172    "social_security_number": "***-**-0000"
173  },
174  "turnaround_time": {
175    "best_estimate": "48",
176    "lower_bound": "20",
177    "upper_bound": "128"
178  },
179  "type": "employment-income",
180  "use_case": "mortgage"
181}
Retrieves a Verification by id.
Was this page helpful?
Previous

Reverify a Verification

Next
Built with

Authentication

AuthorizationBearer
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 `.

Path parameters

verification_request_idstringRequired
Verification ID

Headers

AcceptenumOptionalDefaults to application/json
Specify the content type and version that the API should use. It's recommended to include this to avoid breaking changes.
Allowed values:

Query parameters

fieldsstring or nullOptional

Comma-separated names of fields to include in the response. If omitted, all fields are included

income_analyticsbooleanOptionalDefaults to false
Whether to calculate income analytics for the nested reports

Response headers

Datestring
For JSON requests, the date at which the request was signed
X-Truework-Signaturestring
For JSON requests, the signature of the request, see: https://www.truework.com/docs/verifications-signatures

Response

OK
additional_informationstring or null
Any additional information about the target that can help expedite the completion of the verification request
cancellation_detailsstring or null

The details for the cancellation; only present when state is canceled

cancellation_reasonenum or null
VALUEDESCRIPTION
immediateCan be used to cancel a request directly after submitting, before Truework has started processing it
high-turnaround-timeThe request is taking longer than expected
competitorYou preferred a competitor for this request
wrong-infoThe request that is submitted contains information that is wrong
otherNo other reason in the list fits the cancellation reason
Allowed values:
createddatetime
date_of_completiondatetime or null
The date when this verification was completed in ISO 8601 format
documentslist of objects or null
Supporting documentation files provided by the verifier for the verification
idstring1-128 characters
loan_idstring or null
The loan id associated with the verification request
metadatamap from strings to strings or null

A single level key-value JSON object that can be used to store custom data on the verification request; keys and values must be strings

permissible_purposeenum

A valid purpose is required for Truework to process the verification request. Throughout the API, this is signified by the permissible_purpose field.

VALUEDESCRIPTION
child-supportDetermine child support payments (available to verifiers that represent a state or local child support enforcement agencies)
credit-applicationThe target’s application for credit
employee-eligibilityEmployee’s eligibility for a benefit granted by a governmental agency required by law to consider the employee’s financial responsibility or status
employee-requestThe target has issued the verifier written instruction to obtain this information
employee-review-or-collectionPerforming a review or collection of the target’s account
employmentEmployment purposes where the target has given prior written consent
insurance-underwriting-applicationUnderwriting insurance in response to the target’s application
legitimate-reason-initiatedLegitimate business need for the information in connection with a business transaction initiated by the target
legitimate-reason-reviewLegitimate business need to review the target’s account to determine whether the employee continues to meet the terms of the account
risk-assessmentTo assess the credit or prepayment risks associated with an existing credit obligation of the target
subpoenaFor a court order or a federal grand jury subpoena
priceobject
Currently we only support USD as currency. Currency amounts are represented as strings with two decimal precision, e.g. "34.95".
reportslist of objects or null
Applicable reports belonging to this request, if the request has been completed
request_parametersobject or null
reseller_originating_partyobject or null
The originating party that requested the verification via a reseller.
stateenum

The state helps convey where the verification request is in the Truework process. It will be returned in the JSON objects returned from this endpoint.

The initial state of all Schemas is pending-approval, and will switch to processing once Truework begins to process the request. However, it may switch back to pending-approval if it is pending approval by the target.

The states completed, canceled, invalid are all terminal states of a Verification. A Report is only available when it is in the completed state. A Verification will enter the state canceled when either Truework or an API user cancels the request. The invalid state indicates that there are issues with the data e.g. we could not locate the employee at a given employer, or could not find the employer itself.

VALUEDESCRIPTION
pending-approvalThe initial state after creation; the Truework team has not started working on this request yet
action-requiredA user action is required to continue processing this request; visit the dashboard for more information
invalidContains invalid information that prevents the verification request from being processed by Truework
processingThe Truework team is currently working on the verification request
completedThe verification request has been completed and a report can be found from the reports endpoint
canceledTruework denied processing of the request or the verifier no longer wants the request to be processed
targetobject
turnaround_timeobject

We use data from thousands of verification requests to estimate the duration between creation and completion of a request. For a provided company, upper_bound and lower_bound are the time estimates (in hours) that this particular request will take to be fully processed by Truework. May be an empty if an estimate does not exist for the verification request.

typeenum
Allowed values:
use_caseenum

The verification request use case describes the type of product the verification request is originating from. If omitted, the verifier type in account settings will be used as a default

VALUEDESCRIPTION
mortgageVerification for a mortgage
home-equityVerification for home equity
backgroundVerification for a background check
tenantVerification for a rental property
governmentVerification for government/social services
autoVerification for auto lending
lendingVerification for personal loans or consumer lending
creditVerification for credit cards
identityVerification for identity or fraud
insuranceVerification for insurance
healthVerification for health services
offersVerification for offers
account-managementVerification for account management
preapprovalVerification for preapprovals
otherVerification for other products. This exists for historical compatibility, no new Schemas can be created with this value

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
406
Not Acceptable Error
429
Too Many Requests Error
451
Unavailable for Legal Reasons Error
500
Internal Server Error
501
Not Implemented Error

Bearer tokens conform to the RFC6750 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 .

For JSON requests, the signature of the request, see: https://www.truework.com/docs/verifications-signatures