Skip to main content

Create a Verification

POST https://api.truework.com/verification-requests/

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

Verification Processing

Verifications are generally processed asynchronously: they will be created and returned in the response body without a report. Truework will then send a webhook when the request has finished processing, and the report 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 request within the specified timeout. If successful, the response will include a reports key, which will contain the requsested data. If the timeout cannot be met due to delays while calling our instant network partners, the request will be canceled.

Request#

Request Headers#

PROPERTYTYPEREQUIREDDESCRIPTION
Request-SyncstringA header that defines if a request should be executed synchronously, and how long it can take in seconds

Request-Sync#

This header can take one of the following values, and additionally requires a timeout parameter (in seconds) if a synchronous execution strategy is selected. If the header is not defined, the request will default to asynchronous execution.

Timeout Constraints

The value for timeout must be an integer. The minimum allowable value is 3. The maximum allowable value is 5.

caution

The timeout value is enforced in the application layer. This means that a request may take longer than the specified timeout if the system is under high load, or if network conditions are not ideal. It is highly recommended to set a timeout on the client-side as well.

VALUEDESCRIPTION
sync-strict-timeoutThe request will execute synchronously, and will be canceled if the timeout cannot be met
asyncThe request will execute asynchronously, and will ignore any timeout provided
Strict Timeout Behavior

Requests using the sync-strict-timeout behavior do not generate webhooks. If the timeout cannot be met on a strict request, the response will still be returned, but will have no reports key. The request will then be canceled asynchronously.

Examples#

Synchronous Request with 5 Second Timeout

Request-Sync: sync-strict-timeout; timeout=5

Asynchronous Request

Request-Sync: async

caution

The sync-strict-timeout and sync-soft-timeout options are only valid for requests that do not include a target company. Other requests that pass this header will return a 400 Bad Request error.

Request Body#

PROPERTYTYPEREQUIREDDESCRIPTION
typeTypeType of verification request
permissible_purposePermissiblePurposeReason for why this verification is being conducted
targetTargetInformation on the individual who is being verified
documentsDocument[]Supporting documentation for the verification in PDF format
additional_informationstringAny additional information about the target that can help expedite the completion of the verification request - max: 1k chars.
loan_idstringThe loan id associated with the verification request
metadataJSONA single level key-value JSON object that can be used to store custom data on the verification request; keys and values must be strings
use_caseUseCaseUse case for this request. If omitted, the verifier type in account settings will be used as a default

Target#

PROPERTYTYPEREQUIREDDESCRIPTION
first_namestringFirst name of the target
last_namestringLast name of the target
social_security_numberstringThe target's social security number in format XXX-XX-XXXX or XXXXXXXXX
companyCompanyDetails about the target's company
contact_emailstringTarget's email address
date_of_birthstringTarget's date of birth in format YYYY-MM-DD
caution

When a company is not provided the request will only yield results that are obtainable without a target company. If a relevant match cannot be found, the request will be canceled. For maximum coverage include a company in the request.

Company#

PROPERTYTYPEREQUIREDDESCRIPTION
idstringThe id returned in a company search response; this is required if name is not provided
namestringThe name of the company; this is required if id is not provided
phone_numberstringContact phone number for this company
addressstringStreet address of the company
citystringCity of the company
statestringState of the company
zip_codestringZip code of the company
info

You must provide either an id or a name.

caution

When a company name is provided instead of an id, the request may take longer to process. Additionally, providing an id is required in order to receive the most accurate turnaround times.

Document#

An attachment object requires the following:

PROPERTYTYPEREQUIREDDESCRIPTION
filenamestringName of the file e.g. "authorization.pdf"
contentstringbase64 representation of the PDF file

Response#

Response Body#

The response body from this endpoint is a Verification

Examples#

Request#

$ curl 'https://api.truework.com/verification-requests/' \
-X POST \
-H 'Authorization: Bearer myTrueworkToken' \
-H 'Content-Type: application/json' \
-d '{
"type": "employment",
"permissible_purpose": "risk-assessment",
"target": {
"first_name": "Joe",
"last_name": "Smith",
"social_security_number": "000-00-0000",
"contact_email": "joesmith@example.org",
"company": {
"id": 1234
}
},
"documents": [
{
"filename": "signed_auth_form.pdf",
"content": "iVBORw0KGgoAAAANSUhEUg......IhAAAAABJRU5ErkJggg=="
},
{
"filename": "verifier_notes.pdf",
"content": "iVBORw0KGgoAAAANSUhEUg......IhAAAAABJRU5FRSJghg=="
}
],
"metadata": {
"internal_id": "12454"
}
}'

Response#

{
"id": "AAAAAAAAQnIAAYd5YHFVOm8PNX2ecFbEjqV__upOKUE8YE_IK2GwSQTP",
"created": "2020-01-02T01:46:37.839067Z",
"type": "employment",
"permissible_purpose": "risk-assessment",
"state": "pending-approval",
"target": {
"first_name": "Joe",
"last_name": "Smith",
"social_security_number": "***-**-0000",
"contact_email": "joesmith@example.org",
"company": {
"id": "1234",
"name": "Future Widget LLC"
}
},
"price": {
"amount": "34.95",
"currency": "USD"
},
"turnaround_time": {
"upper_bound": "42",
"best_estimate": "34",
"lower_bound": "23"
},
"documents": [
{
"filename": "signed_auth_form.pdf"
},
{
"filename": "verifier_notes.pdf"
}
],
"metadata": {
"internal_id": "12454"
}
}