Create a target employer order

POST

/orders/target-employer

POST

/orders/target-employer

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

Try it

1 {
2   "id": "AAAAAAAAAosABwGqF1AUKAH0-puth1tCzLNar3Jyb4bx3wdVKU99XC26",
3   "employer_search": {
4     "permissible_purpose": {
5       "canonical_value": "child-support",
6       "raw_value": "raw_value"
7     },
8     "request_config": {
9       "employer_filter": "any-employers",
10       "required_eligibilities": [
11         "d1c"
12       ]
13     },
14     "target": {
15       "contact_email": "contact_email",
16       "date_of_birth": "1985-12-20",
17       "first_name": "Jane",
18       "last_name": "Doe",
19       "social_security_number": "***-**-0000"
20     },
21     "type": "employment-income",
22     "use_case": {
23       "canonical_value": "mortgage",
24       "raw_value": "raw_value"
25     },
26     "additional_information": "some notes about the target",
27     "authorization_forms": [
28       {
29         "filename": "test.pdf"
30       }
31     ],
32     "loan_id": "1234",
33     "metadata": {
34       "key": "value"
35     },
36     "reseller_originating_party": {
37       "originating_party": "Acme Corporation",
38       "permissible_purpose": {
39         "canonical_value": "child-support",
40         "raw_value": "raw_value"
41       },
42       "use_case": {
43         "canonical_value": "mortgage",
44         "raw_value": "raw_value"
45       }
46     },
47     "search_key": "12345"
48   },
49   "loan_id": "1234",
50   "reverification": {
51     "parent_order_id": "parent_order_id",
52     "targets": [
53       {
54         "first_name": "first_name",
55         "last_name": "last_name"
56       }
57     ]
58   },
59   "search_key": "internal_key_12345",
60   "target_employer": {
61     "permissible_purpose": {
62       "canonical_value": "child-support",
63       "raw_value": "raw_value"
64     },
65     "request_config": {
66       "allowed_verification_methods": [
67         "instant"
68       ],
69       "required_eligibilities": [
70         "d1c"
71       ]
72     },
73     "target": {
74       "company": {
75         "name": "Acme Inc"
76       },
77       "contact_email": "contact_email",
78       "date_of_birth": "1985-12-20",
79       "first_name": "Jane",
80       "last_name": "Doe",
81       "social_security_number": "***-**-0000"
82     },
83     "type": "employment-income",
84     "use_case": {
85       "canonical_value": "mortgage",
86       "raw_value": "raw_value"
87     },
88     "additional_information": "some notes about the target",
89     "authorization_forms": [
90       {
91         "filename": "test.pdf"
92       }
93     ],
94     "loan_id": "1234",
95     "metadata": {
96       "key": "value"
97     },
98     "reseller_originating_party": {
99       "originating_party": "Acme Corporation",
100       "permissible_purpose": {
101         "canonical_value": "child-support",
102         "raw_value": "raw_value"
103       },
104       "use_case": {
105         "canonical_value": "mortgage",
106         "raw_value": "raw_value"
107       }
108     },
109     "search_key": "12345"
110   },
111   "truework_direct": {
112     "targets": [
113       {
114         "date_of_birth": "1990-05-20",
115         "permissible_purpose": {
116           "canonical_value": "child-support",
117           "raw_value": "raw_value"
118         },
119         "social_security_number": "***-**-0000",
120         "truework_direct_session_token": "tjs_i1D3IHdW52_vsLP5vQTng7vXBX93UD_7UdtVOIH2qVQ",
121         "type": "employment-income",
122         "use_case": {
123           "canonical_value": "mortgage",
124           "raw_value": "raw_value"
125         },
126         "companies": [
127           {
128             "name": "Acme Corp"
129           }
130         ],
131         "contact_email": "jane.doe@example.com",
132         "first_name": "Jane",
133         "last_name": "Doe",
134         "reseller_originating_party": {
135           "originating_party": "Acme Corporation",
136           "permissible_purpose": {
137             "canonical_value": "child-support",
138             "raw_value": "raw_value"
139           },
140           "use_case": {
141             "canonical_value": "mortgage",
142             "raw_value": "raw_value"
143           }
144         },
145         "truework_direct_session_link": "https://app.truework.com/api/connect/employee/email/tjs_i1D3IHdW52_vsLP5vQTng7vXBX93UD_7UdtVOIH2qVQ"
146       }
147     ]
148   },
149   "truework_direct_session_link": "truework_direct_session_link",
150   "verification_requests": [
151     {
152       "created": "2021-12-20T18:50:20Z",
153       "id": "AAAAAAAAAosABwGqF1AUKAH0-puth1tCzLNar3Jyb4bx3wdVKU99XC26",
154       "permissible_purpose": {
155         "canonical_value": "child-support",
156         "raw_value": "raw_value"
157       },
158       "state": {
159         "canonical_value": "pending-approval",
160         "raw_value": "raw_value"
161       },
162       "target": {
163         "first_name": "Jane",
164         "last_name": "Doe",
165         "social_security_number": "***-**-0000"
166       },
167       "turnaround_time": {
168         "best_estimate": "48",
169         "lower_bound": "20",
170         "upper_bound": "128"
171       },
172       "type": "employment-income",
173       "use_case": {
174         "canonical_value": "mortgage",
175         "raw_value": "raw_value"
176       },
177       "additional_information": "some notes about the target",
178       "applicant_documents": [
179         {
180           "detections": [
181             {
182               "count": 1,
183               "outcome": {
184                 "canonical_value": "passed",
185                 "raw_value": "raw_value"
186               },
187               "type": {
188                 "canonical_value": "ssn-mismatch",
189                 "raw_value": "raw_value"
190               }
191             }
192           ],
193           "id": "AAAAAAAAA3IAF7BGt6e3K0DXcz2pU2ZnvhxOzrfckvfNROXjJN9Rf6oV",
194           "url": "url"
195         }
196       ],
197       "cancellation_details": "cancellation_details",
198       "cancellation_reason": {
199         "canonical_value": "immediate",
200         "raw_value": "raw_value"
201       },
202       "date_of_completion": "2021-12-20T18:50:20Z",
203       "documents": [
204         {
205           "filename": "test.pdf"
206         }
207       ],
208       "loan_id": "1234",
209       "reports": [
210         {
211           "created": "2021-12-20T18:50:20Z",
212           "current_as_of": "2021-12-20",
213           "id": "AAAAAAAADU8ACy03lGitY_ocCMCcgproUq8Gt4r37MM6GbyX2-DxWM3Y",
214           "verification_request": {
215             "created": "2021-12-20T18:50:20Z",
216             "id": "AAAAAAAAEboABwQhKv1_pWO7MWtZs28ksPTH0uSt6GffsoIJPj7e69P1",
217             "type": "employment-income"
218           },
219           "applicant_documents": [
220             {
221               "detections": [
222                 {
223                   "count": 1,
224                   "outcome": {
225                     "canonical_value": "passed",
226                     "raw_value": "raw_value"
227                   },
228                   "type": {
229                     "canonical_value": "ssn-mismatch",
230                     "raw_value": "raw_value"
231                   }
232                 }
233               ],
234               "id": "AAAAAAAAA3IAF7BGt6e3K0DXcz2pU2ZnvhxOzrfckvfNROXjJN9Rf6oV",
235               "url": "url"
236             }
237           ],
238           "disputes": [
239             {
240               "created": "2021-12-20T18:50:20Z",
241               "id": "AAAAAAAAAL8AElevkrw2n2vI8ScqGJEf50Lfg4W9LiQXwi-KSmg7DH0P",
242               "description": "Employee Title",
243               "reference_id": "d75346a0-a747-4907-a506-639ea436f2b0"
244             }
245           ],
246           "financial_institution_accounts": [
247             {
248               "income_streams": [
249                 {
250                   "confidence": 1,
251                   "confidence_level": "confidence_level",
252                   "id": "AAAAAAAAAosABwGqF1AUKAH0-puth1tCzLNar3Jyb4bx3wdVKU99XC31",
253                   "name": "name",
254                   "periods": [
255                     {
256                       "amount_duration": "amount_duration",
257                       "amount_type": "amount_type",
258                       "id": "AAAAAAAAAosABwGqF1AUKAH0-puth1tCzLNar3Jyb4bx3wdVKU99XC31",
259                       "start_day": "start_day"
260                     }
261                   ],
262                   "status": "status"
263                 }
264               ],
265               "snapshots": [
266                 {
267                   "id": "AAAAAAAAAosABwGqF1AUKAH0-puth1tCzLNar3Jyb4bx3wdVKU99XC31"
268                 }
269               ]
270             }
271           ],
272           "paystubs": [
273             {
274               "id": "AAAAAAAAAmEADp7bmZJNhm4Kr5FM_ty5A_JX-Rxh04GSIHwmIRyp6Xss",
275               "base": "7000.00",
276               "bonus": "1000.00",
277               "commission": "0.00",
278               "gross": "8000.00",
279               "net": "5500.00",
280               "other": "0.00",
281               "overtime": "0.00",
282               "pay_period_hours": "86.67",
283               "reference_id": "6894632654"
284             }
285           ]
286         }
287       ],
288       "reseller_originating_party": {
289         "originating_party": "Acme Corporation",
290         "permissible_purpose": {
291           "canonical_value": "child-support",
292           "raw_value": "raw_value"
293         },
294         "use_case": {
295           "canonical_value": "mortgage",
296           "raw_value": "raw_value"
297         }
298       }
299     }
300   ]
301 }

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

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

targetobjectRequired

Information on the individual who is being verified

typeenumRequired

Allowed values:

use_caseenumRequired

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

additional_informationstringOptional

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

authorization_formslist of objectsOptional

Authorization form 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_configobjectOptional

reseller_originating_partyobjectOptional

The originating party that requested the verification via a reseller. reseller_originating_party is required for for companies that resell data provided by Truework.

search_keystringOptional

A non-unique key that can be used to search for Orders

tenant_property_idstringOptional

The ID of the tenant property to be used for this verification request.

Response

Order Request Created.

idstring>=1 character<=128 characters

employer_searchobject or null

Response object specific to Employer Search requests.

loan_idstring or null

The loan id associated with the verification request

reverificationobject or null

Response object specific to Reverification requests.

search_keystring or null

A non-unique key that can be used to search for Orders

target_employerobject or null

Response object specific to Target Employer requests.

truework_directobject or null

Response object specific to Truework Direct requests.

truework_direct_session_linkstring or null

The Truework Direct URL that is emailed to the applicant for eligible orders. Will only be present when the order is using Truework Direct via email for fulfillment, and the session is prepared for input from the applicant.

verification_requestslist of objects or null

Create a target employer order

Verification processing

Controlling Processing with request config

Headers

Request

Response

Errors