Create an employer search order

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

Headers

AuthorizationstringRequired

Bearer authentication of the form Bearer <token>, where token is your auth token.

Accept"application/json"Required
Specify the content type and version that the API should use. It's recommended to include this to avoid breaking changes.

Query parameters

fieldsstringOptional

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.

include_income_analyticsbooleanOptionalDefaults to false
Whether to calculate income analytics for the nested reports in each verification.
include_report_annotationsbooleanOptionalDefaults to false
Include potentially unverified data in the response, including report annotations and unparsed documents.

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.

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

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

Response

Order and Verification Request Created.
idstring>=1 character<=128 characters
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.
verification_requestslist of objects or null

Errors