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#
| 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 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.
| VALUE | DESCRIPTION |
|---|---|
| sync-strict-timeout | The request will execute synchronously, and will be canceled if the timeout cannot be met |
| async | The 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#
| 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
- Ruby
- Node