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.

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

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

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=="
} ]
}'
{
"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"
}
]
}