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 the timeout cannot be met due to delays while calling our
instant network partners, the request can either be canceled, or fallback to asynchronous execution.
Request#
Request Headers#
| PROPERTY | TYPE | REQUIRED | DESCRIPTION |
|---|---|---|---|
| Request-Sync | string | A 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 passed in only limits the execution phase of the request, not the entire request. This means that a
request may take a few hundred milliseconds longer than the specified timeout once request processing and network
traversal is accounted for. If the request is subject to strict time constraints, it is recommended to set a timeout on
the client-side as well.
| VALUE | DESCRIPTION |
|---|---|
| sync-strict-timeout | The request will execute synchronously, and will be canceled if the timeout cannot be met |
| sync-soft-timeout | The request will executes synchronously, and will fallback to asynchronous processing if the timeout cannot be met |
| async | The request will execute asynchronously, and will ignore any timeout provided |
Strict Timeout Behavior
Examples#
Synchronous Request with 5 Second Strict Timeout
Request-Sync: sync-strict-timeout; timeout=5
Synchronous Request with 3 Second Soft Timeout
Request-Sync: sync-soft-timeout; timeout=3
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#
| 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 in PDF format | |
| additional_information | string | Any additional information about the target that can help expedite the completion of the verification request - max: 1k chars. | |
| loan_id | string | The loan id associated with the verification request | |
| metadata | JSON | 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 | |
| use_case | UseCase | Use case for this request. If omitted, the verifier type in account settings will be used as a default |
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 | |
| phone_number | string | Contact phone number for this company | |
| address | string | Street address of the company | |
| city | string | City of the company | |
| state | string | State of the company | |
| zip_code | string | Zip 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:
| PROPERTY | TYPE | REQUIRED | DESCRIPTION |
|---|---|---|---|
| filename | string | Name of the file e.g. "authorization.pdf" | |
| content | string | base64 representation of the PDF file |
Response#
Response Body#
The response body from this endpoint is a Verification
Examples#
Request#
- cURL
- Python
- Ruby
- Node