Create a Verification | Truework Docs

Creates a new Verification and return a JSON object representing the newly created Verification.

Verification Processing

Controlling Processing with the `Request-Sync` Header

Verifications are generally processed asynchronously: they will be created and returned in the response body without any reports. Truework will then send a webhook when the request has finished processing, and the reports can be retrieved. However, Instant verifications (those which are created without a target company) can also be executed synchronously by using the Request-Sync header. When processing 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.

This header can take one of the following values. If the header is not defined, the request will default to asynchronous execution.

VALUE	DESCRIPTION
sync	The request will execute synchronously
async	The request will execute asynchronously

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.

Synchronous execution is only valid for requests that do not include a target company. Other requests that pass this header will return a 400 response.

Controlling Processing with Request Parameters

Request parameters allow you to configure how you use Truework by selecting only the verification methods and features you need. If the request_parameters field is left blank, the default behavior is:

If target.company is included:
- Enable all verification methods
- Set automated_underwriting_system_eligibility to not-required
- Set employer_filter to target-employer
If target.company is omitted:
- Only enable Truework Instant
- Set automated_underwriting_system_eligibility to not-required
- Set employer_filter to all-employers or previous-employers

Creates a new Verification and return a JSON object representing the newly created Verification. ## Verification Processing ### Controlling Processing with the `Request-Sync` Header Verifications are generally 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. However, **Instant** verifications (those which are created without a target company) can also be executed _synchronously_ by using the `Request-Sync` header. When processing 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. This header can take one of the following values. If the header is not defined, the request will default to asynchronous execution. | VALUE | DESCRIPTION | | ----- | --------------------------------------- | | sync | The request will execute synchronously | | async | The request will execute asynchronously | 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. Synchronous execution is only valid for requests that do not include a target company. Other requests that pass this header will return a `400` response. ### Controlling Processing with Request Parameters Request parameters allow you to configure how you use Truework by selecting only the verification methods and features you need. If the `request_parameters` field is left blank, the default behavior is: - If `target.company` is included: - Enable all verification methods - Set `automated_underwriting_system_eligibility` to `not-required` - Set `employer_filter` to `target-employer` - If `target.company` is omitted: - Only enable Truework Instant - Set `automated_underwriting_system_eligibility` to `not-required` - Set `employer_filter` to `all-employers` or `previous-employers`

Headers

Query parameters

fieldsstringOptional

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 in each verification.

Request

This endpoint expects an object.

permissible_purposeenumRequired

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

VALUE	DESCRIPTION
child-support	Determine child support payments (available to verifiers that represent a state or local child support enforcement agencies)
credit-application	The target’s application for credit
employee-eligibility	Employee’s eligibility for a benefit granted by a governmental agency required by law to consider the employee’s financial responsibility or status
employee-request	The target has issued the verifier written instruction to obtain this information
employee-review-or-collection	Performing a review or collection of the target’s account
employment	Employment purposes where the target has given prior written consent
insurance-underwriting-application	Underwriting insurance in response to the target’s application
legitimate-reason-initiated	Legitimate business need for the information in connection with a business transaction initiated by the target
legitimate-reason-review	Legitimate business need to review the target’s account to determine whether the employee continues to meet the terms of the account
risk-assessment	To assess the credit or prepayment risks associated with an existing credit obligation of the target
subpoena	For a court order or a federal grand jury subpoena

A valid purpose is required for Truework to process the verification request. Throughout the API, this is signified by the `permissible_purpose` field. | VALUE | DESCRIPTION | | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | child-support | Determine child support payments (available to verifiers that represent a state or local child support enforcement agencies) | | credit-application | The target's application for credit | | employee-eligibility | Employee's eligibility for a benefit granted by a governmental agency required by law to consider the employee's financial responsibility or status | | employee-request | The target has issued the verifier written instruction to obtain this information | | employee-review-or-collection | Performing a review or collection of the target's account | | employment | Employment purposes where the target has given prior written consent | | insurance-underwriting-application | Underwriting insurance in response to the target's application | | legitimate-reason-initiated | Legitimate business need for the information in connection with a business transaction initiated by the target | | legitimate-reason-review | Legitimate business need to review the target's account to determine whether the employee continues to meet the terms of the account | | risk-assessment | To assess the credit or prepayment risks associated with an existing credit obligation of the target | | subpoena | For a court order or a federal grand jury subpoena

targetobjectRequired

Information on the individual who is being verified

typeenumRequired

Allowed values:

additional_informationstringOptional

Any additional information about the target that can help expedite the completion of the verification request

documentslist of objectsOptional

Supporting documentation files provided by the verifier for the verification

loan_idstringOptional

The loan id associated with the verification request

metadatamap from strings to optional stringsOptional

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

request_parametersobjectOptional

reseller_originating_partyobjectOptional

The originating party that requested the verification via a reseller.

use_caseenumOptional

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

VALUE	DESCRIPTION
mortgage	Verification for a mortgage
home-equity	Verification for home equity
background	Verification for a background check
tenant	Verification for a rental property
government	Verification for government/social services
auto	Verification for auto lending
lending	Verification for personal loans or consumer lending
credit	Verification for credit cards
identity	Verification for identity or fraud
insurance	Verification for insurance
health	Verification for health services
offers	Verification for offers
account-management	Verification for account management
preapproval	Verification for preapprovals

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 | VALUE | DESCRIPTION | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------ | | mortgage | Verification for a mortgage | | home-equity | Verification for home equity | background | Verification for a background check | | tenant | Verification for a rental property | | government | Verification for government/social services | | auto | Verification for auto lending | | lending | Verification for personal loans or consumer lending | | credit | Verification for credit cards | | identity | Verification for identity or fraud | | insurance | Verification for insurance | | health | Verification for health services | | offers | Verification for offers | | account-management | Verification for account management | | preapproval | Verification for preapprovals |

Response

Verification Request Created.

createddatetime

idstring>=1 character<=128 characters

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.

VALUE	DESCRIPTION
child-support	Determine child support payments (available to verifiers that represent a state or local child support enforcement agencies)
credit-application	The target’s application for credit
employee-eligibility	Employee’s eligibility for a benefit granted by a governmental agency required by law to consider the employee’s financial responsibility or status
employee-request	The target has issued the verifier written instruction to obtain this information
employee-review-or-collection	Performing a review or collection of the target’s account
employment	Employment purposes where the target has given prior written consent
insurance-underwriting-application	Underwriting insurance in response to the target’s application
legitimate-reason-initiated	Legitimate business need for the information in connection with a business transaction initiated by the target
legitimate-reason-review	Legitimate business need to review the target’s account to determine whether the employee continues to meet the terms of the account
risk-assessment	To assess the credit or prepayment risks associated with an existing credit obligation of the target
subpoena	For 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".

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.

VALUE	DESCRIPTION
pending-approval	The initial state after creation; the Truework team has not started working on this request yet
action-required	A user action is required to continue processing this request; visit the dashboard for more information
invalid	Contains invalid information that prevents the verification request from being processed by Truework
processing	The Truework team is currently working on the verification request
completed	The verification request has been completed and a report can be found from the reports endpoint
canceled	Truework denied processing of the request or the verifier no longer wants the request to be processed

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. | VALUE | DESCRIPTION | | ---------------- | ------------------------------------------------------------------------------------------------------- | | pending-approval | The initial state after creation; the Truework team has not started working on this request yet | | action-required | A user action is required to continue processing this request; visit the dashboard for more information | | invalid | Contains invalid information that prevents the verification request from being processed by Truework | | processing | The Truework team is currently working on the verification request | | completed | The verification request has been completed and a report can be found from the reports endpoint | | canceled | Truework 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

VALUE	DESCRIPTION
mortgage	Verification for a mortgage
home-equity	Verification for home equity
background	Verification for a background check
tenant	Verification for a rental property
government	Verification for government/social services
auto	Verification for auto lending
lending	Verification for personal loans or consumer lending
credit	Verification for credit cards
identity	Verification for identity or fraud
insurance	Verification for insurance
health	Verification for health services
offers	Verification for offers
account-management	Verification for account management
preapproval	Verification for preapprovals
other	Verification for other products. This exists for historical compatibility, no new Schemas can be created with this value

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

VALUE	DESCRIPTION
immediate	Can be used to cancel a request directly after submitting, before Truework has started processing it
high-turnaround-time	The request is taking longer than expected
competitor	You preferred a competitor for this request
wrong-info	The request that is submitted contains information that is wrong
other	No other reason in the list fits the cancellation reason

| VALUE | DESCRIPTION | | -------------------- | ---------------------------------------------------------------------------------------------------- | | immediate | Can be used to cancel a request directly after submitting, before Truework has started processing it | | high-turnaround-time | The request is taking longer than expected | | competitor | You preferred a competitor for this request | | wrong-info | The request that is submitted contains information that is wrong | | other | No other reason in the list fits the cancellation reason |

Allowed values:

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

loan_idstring or null

The loan id associated with the verification request

metadatamap from strings to optional 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

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.

Errors

Creates a new Verification and return a JSON object representing the newly created Verification.

Verification Processing

Controlling Processing with the `Request-Sync` Header

This header can take one of the following values. If the header is not defined, the request will default to asynchronous execution.

VALUE	DESCRIPTION
sync	The request will execute synchronously
async	The request will execute asynchronously

Synchronous execution is only valid for requests that do not include a target company. Other requests that pass this header will return a 400 response.

Controlling Processing with Request Parameters

If target.company is included:
- Enable all verification methods
- Set automated_underwriting_system_eligibility to not-required
- Set employer_filter to target-employer
If target.company is omitted:
- Only enable Truework Instant
- Set automated_underwriting_system_eligibility to not-required
- Set employer_filter to all-employers or previous-employers

1	import requests
2
3	url = "https://api.truework-sandbox.com/verification-requests"
4
5	querystring = {"fields":"id,status"}
6
7	payload = {
8	"permissible_purpose": "child-support",
9	"target": {
10	"first_name": "Jane",
11	"last_name": "Doe",
12	"social_security_number": "000-00-0000"
13	},
14	"type": "employment-income"
15	}
16	headers = {
17	"Accept": "application/json",
18	"Request-Sync": "async",
19	"Authorization": "Bearer <token>",
20	"Content-Type": "application/json"
21	}
22
23	response = requests.post(url, json=payload, headers=headers, params=querystring)
24
25	print(response.json())

1	{
2	"created": "2021-12-20T18:50:20Z",
3	"id": "AAAAAAAAAosABwGqF1AUKAH0-puth1tCzLNar3Jyb4bx3wdVKU99XC26",
4	"permissible_purpose": "child-support",
5	"price": {
6	"amount": "34.95",
7	"currency": "USD"
8	},
9	"state": "pending-approval",
10	"target": {
11	"first_name": "Jane",
12	"last_name": "Doe",
13	"company": {
14	"address": "address",
15	"city": "city",
16	"id": 1,
17	"name": "Example Inc.",
18	"phone_number": "phone_number",
19	"state": "state",
20	"zip_code": "zip_code"
21	},
22	"contact_email": "contact_email",
23	"date_of_birth": "date_of_birth",
24	"phone_number": "phone_number",
25	"social_security_number": "*--0000"
26	},
27	"turnaround_time": {
28	"best_estimate": "48",
29	"lower_bound": "20",
30	"upper_bound": "128"
31	},
32	"type": "employment-income",
33	"use_case": "mortgage",
34	"additional_information": "additional_information",
35	"cancellation_details": "cancellation_details",
36	"cancellation_reason": "immediate",
37	"date_of_completion": "2021-12-20T18:50:20Z",
38	"documents": [
39	{
40	"filename": "test.pdf"
41	}
42	],
43	"loan_id": "loan_id",
44	"metadata": {
45	"key": "value"
46	},
47	"reports": [
48	{
49	"created": "2021-12-20T18:50:20Z",
50	"current_as_of": "2021-12-20",
51	"disputes": [
52	{
53	"created": "2021-12-20T18:50:20Z",
54	"description": "Employee Title",
55	"id": "AAAAAAAAAL8AElevkrw2n2vI8ScqGJEf50Lfg4W9LiQXwi-KSmg7DH0P",
56	"reference_id": "d75346a0-a747-4907-a506-639ea436f2b0"
57	}
58	],
59	"employee": {
60	"first_name": "Jane",
61	"last_name": "Doe",
62	"positions": [
63	{
64	"employment_type": "regular-full-time",
65	"title": "Software Engineer"
66	}
67	],
68	"status": "active",
69	"status_detail": "active",
70	"earnings": [
71	{
72	"base": "35000.00",
73	"bonus": "0.00",
74	"commission": "100.25",
75	"other": "0.00",
76	"overtime": "200.00",
77	"termination": false,
78	"total": "35300.25",
79	"year": "2020"
80	}
81	],
82	"salary": {
83	"reduced_covid": "yes",
84	"hours_per_week": "40",
85	"months_per_year": "12"
86	},
87	"social_security_number": "*--0000"
88	},
89	"employer": {
90	"name": "name",
91	"government_ids": [
92	{
93	"id": "123456789",
94	"type": "us-fein"
95	}
96	]
97	},
98	"id": "AAAAAAAADU8ACy03lGitY_ocCMCcgproUq8Gt4r37MM6GbyX2-DxWM3Y",
99	"verification_request": {
100	"created": "2021-12-20T18:50:20Z",
101	"id": "AAAAAAAAEboABwQhKv1_pWO7MWtZs28ksPTH0uSt6GffsoIJPj7e69P1",
102	"type": "employment-income"
103	},
104	"additional_notes": "additional_notes",
105	"d1c_eligible": true,
106	"du_reference_id": "du_reference_id",
107	"paystubs": [
108	{
109	"id": "AAAAAAAAAmEADp7bmZJNhm4Kr5FM_ty5A_JX-Rxh04GSIHwmIRyp6Xss",
110	"base": "7000.00",
111	"bonus": "1000.00",
112	"commission": "0.00",
113	"gross": "8000.00",
114	"net": "5500.00",
115	"other": "0.00",
116	"overtime": "0.00",
117	"pay_period_hours": "86.67",
118	"reference_id": "6894632654"
119	}
120	],
121	"pricing_tier": "instant"
122	}
123	],
124	"request_parameters": {
125	"automated_underwriting_system_eligibility": "not-required",
126	"employer_filter": "target-employer",
127	"verification_methods": {
128	"credentials": {
129	"enabled": true
130	},
131	"instant": {
132	"enabled": true
133	},
134	"smart_outreach": {
135	"enabled": true
136	}
137	}
138	},
139	"reseller_originating_party": {
140	"originating_party": "originating_party",
141	"permissible_purpose": "child-support",
142	"use_case": "mortgage"
143	}
144	}

Verification Processing

Controlling Processing with the Request-Sync Header

Controlling Processing with Request Parameters

Headers

Query parameters

Request

Response

Errors

Verification Processing

Controlling Processing with the Request-Sync Header

Controlling Processing with Request Parameters

Controlling Processing with the `Request-Sync` Header

Controlling Processing with the `Request-Sync` Header