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
| PROPERTY | TYPE | REQUIRED | DESCRIPTION |
|---|---|---|---|
| type | Type | Type of verification request. | |
| permissible_purpose | PermissiblePurpose | Reason for why this verification is being conducted | |
| target | Target | Information on the individual who is being verified | |
| documents | Document[] | Supporting documentation for the verification | |
| additional_information | string | Any additional information about the target that can help expedite the completion of the verification request - max: 1k chars. |
Target
| PROPERTY | TYPE | REQUIRED | DESCRIPTION |
|---|---|---|---|
| first_name | string | First name of the target | |
| last_name | string | Last name of the target | |
| social_security_number | string | The target's social security number in format XXX-XX-XXXX or XXXXXXXXX | |
| company | Company | Details about the target's company | |
| contact_email | string | Target's email address | |
| date_of_birth | string | Target'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
| PROPERTY | TYPE | REQUIRED | DESCRIPTION |
|---|---|---|---|
| id | string | The id returned in a company search response. This is required if name is not provided. | |
| name | string | The 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:
| PROPERTY | TYPE | REQUIRED | DESCRIPTION |
|---|---|---|---|
| filename | string | Name of the file e.g. "authorization.pdf" | |
| content | string | base64 representation of the file |
Response
Response Body
| PROPERTY | TYPE | NULLABLE | DESCRIPTION |
|---|---|---|---|
| id | string | The id of the verification request | |
| created | string | Creation date of verification request in ISO 8601 format | |
| type | Type | Type of verification report | |
| permissible_purpose | PermissiblePurpose | Reason for why this verification is being conducted | |
| state | State | State of the verification request | |
| target | Target | Information about the verification request target | |
| price | Price | Billing information about how much the verification request will cost once completed | |
| turnaround_time | TurnaroundTime | Expected turnaround time in hours for the verification request. Will be an empty if an estimate does not exist for the verification request | |
| loan_id | string | The loan_id associated with the verification request | |
| cancellation_reason | string | The reason for the cancellation of the request. Only present when state is 'canceled' | |
| cancellation_details | string | The details for the cancellation. Only present when state is 'canceled' and available. | |
| documents | Document[] | Supporting documentation files provided by the verifier for the verification | |
| reports | Report[] | Applicable reports belonging to this request, if the request has been completed |
Price
| PROPERTY | TYPE | NULLABLE | DESCRIPTION |
|---|---|---|---|
| amount | string | Price of the request in string format | |
| currency | string | Currency 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
| PROPERTY | TYPE | NULLABLE | DESCRIPTION |
|---|---|---|---|
| upper_bound | string | The estimated upper bound in hours | |
| best_estimate | string | The best estimate of turnaround time in hours | |
| lower_bound | string | The 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
- Python
- Ruby
- Node