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.

Request#

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

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 file

Response#

Response Body#

PROPERTYTYPENULLABLEDESCRIPTION
idstringThe id of the verification request
createdstringCreation date of verification request in ISO 8601 format
typeTypeType of verification report
permissible_purposePermissiblePurposeReason for why this verification is being conducted
stateStateState of the verification request
targetTargetInformation about the verification request target
pricePriceBilling information about how much the verification request will cost once completed
turnaround_timeTurnaroundTimeExpected turnaround time in hours for the verification request. Will be an empty if an estimate does not exist for the verification request
loan_idstringThe loan_id associated with the verification request
cancellation_reasonstringThe reason for the cancellation of the request. Only present when state is 'canceled'
cancellation_detailsstringThe details for the cancellation. Only present when state is 'canceled' and available.
documentsDocument[]Supporting documentation files provided by the verifier for the verification
reportsReport[]Applicable reports belonging to this request, if the request has been completed
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.

Price#

PROPERTYTYPENULLABLEDESCRIPTION
amountstringPrice of the request in string format
currencystringCurrency of the price
note

Currently we only support USD as currency. Currency amounts are represented as strings with two decimal precision, e.g. "34.95".

TurnaroundTime#

PROPERTYTYPENULLABLEDESCRIPTION
upper_boundstringThe estimated upper bound in hours
best_estimatestringThe best estimate of turnaround time in hours
lower_boundstringThe estimated lower bound in hours

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.

caution

When submitting verification requests by the target's company name instead of id, there will be no estimated turnaround time. In that case the TurnaroundTime is an empty dictionary.

Examples#

$ 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"
}
}'
{
"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",
"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"
}
}