All URLs in the Truework documentation use the following URL as the base:
https://api.truework.com
Assuming you have the token "myTrueworkToken" (without quotes) you query the API as follows:
1
2
curl https://api.truework.com \
-H "Authorization: Bearer myTrueworkToken"
Make sure to replace
myTrueworkToken
with your Truework API Key.
Truework uses Bearer Authentication (also called token authentication).
Authorization: Bearer myTrueworkToken
You can request a token from the configuration page of your account, found here.
The Truework API safeguards itself from bursts of incoming traffic by employing API limits on each endpoint. After these limits are exceeded, 429 responses will be returned and requests will not be serviced. We recommend an exponential backoff of your requests once receiving 429 requests from the API.
Under each section a table will show you the rate limits for that particular endpoint as such:
Rate Type | Limit |
---|---|
IP | 10/s |
Account | 10/s |
Rate types:
We can lift some rate limits if you need to do more requests.
Please visit help.truework.com for more information on how verifications are done, turn around times etc...
Truework uses standard HTTP codes to specify whether the request succeeded or failed. Here is a summary of status codes that we return in our API:
2XX
- The request was successful.
400
- The request provided missing or invalid data. An error response will be returned in JSON format containing an error
field.
401
- The request's authorization is missing, invalid, or expired.
404
- The requested resource does not exist.
500
- The request could not be completed due to an internal server error. If this issue persists, please contact us at api@truework.com
This document covers the Truework API version 1 (v1
). We implicitly version our APIs. You do not need to set that version and it's added automatically in the "version".
Required parameters are marked bold in the documentation below and do not have a default value. Optional parameters will use a default value if not provided.
Bolded fields will always be present in the response body while other fields may be omitted.
Request:
1
2
3
4
curl 'https://api.truework.com/companies/?q=widgets' \
-X GET \
-H 'Authorization: Bearer myTrueworkToken' \
-H 'Content-Type: application/json'
Response:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
"results": [
{
"name": "Bob's Widgets",
"id": 57
},
{
"domain": "futuristic-widgets.example.com",
"name": "Future Widget",
"id": 1234
},
{
"domain": "widgets-and-pizza.example.com",
"name": "National Pizza With Extras LLC",
"id": 4545
}
],
// ... Further 17 results omitted in example
"next": "https://api.truework.com/companies/?q=widgets&offset=20",
"count": 44
}
GET https://api.truework.com/companies/
The company search endpoint can be used to search for a company by its name or domain.
This endpoint supports pagination when given the offset
and limit
parameters. The response will return next
and previous
URLs for the next and previous page, respectively.
Parameter | Type | Default | Description |
---|---|---|---|
q | string | Query string to search companies by name or domain | |
offset | int | 0 | Offset to begin the company search results at |
limit | int | 0 | Number of results to return in the response |
Field | Type | Description |
---|---|---|
results | array of CompanySearchResult |
List of company results based on search |
next | string | URL for next page of results |
previous | string | URL for previous page of results |
count | int | Total number of results |
Field | Type | Description |
---|---|---|
id | int | ID of company |
domain | string | Domain of company |
name | string | Legal name of company |
Truework offers two types of verifications, Verification of Employment (VOE) and Verification of Income (VOI). A VOE will result in a report that contains the target's position, start and end dates at a given employer. A VOI will include all information provided in a VOE along with salary and earnings over the last three years if available.
A verifier can programmatically generate and receive information about VOEs and VOIs through this REST API.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
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==" \
} ] \
}'
The above command returns a JSON response like this:
1
2
3
4
5
6
7
8
9
10
11
12
13
{
"id": "AAAAAAAAQnIAAYd5YHFVOm8PNX2ecFbEjqV__upOKUE8YE_IK2GwSQTP",
"state": "pending-approval",
"price": {
"amount": "33.95",
"currency":"USD"
},
"turnaround_time": {
"upper_bound": 42,
"lower_bound": 23
},
"created": "2008-09-15T15:53:00Z"
}
POST https://api.truework.com/verification-requests/
Call this endpoint to create a new verification of employment. Optional parameters are not required but help reduce the time to accurately verify an employee.
This endpoint will return all the information you need to access the report once completed.
Parameter | Type | Description |
---|---|---|
type | Type |
Type of verification report. See below for more details. |
permissible_purpose | string | How the information in this verification will be used. Can be one of of the PermissiblePurposeType s listed below |
target | Target |
Information on the individual who is being verified |
documents | array of 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 |
Type
One of the following:
employment
to obtain a Verification of Employment (VOE)employment-income
for a Verification of Income (VOI)PermissiblePurposeType
One of the following:
credit-application
: The target's application for credit.employment
: Employment purposes where the target has given prior written consent.employee-eligibility
: Employee's eligibility for a benefit granted by a governmental agency required by law to consider the employee's financial responsibility or status.child-support
: Determine child support payments (available to verifiers that represent a state or local child support enforcement agencies)employee-review-or-collection
: Performing a review or collection of the target's account.employee-request
: The target has issued the verifier written instruction to obtain this information.subpoena
: For a court order or a federal grand jury subpoena.insurance-underwriting-application
: Underwriting insurance in response to the target's application.risk-assessment
: To assess the credit or prepayment risks associated with an existing credit obligation of the target.legitimate-reason-initiated
: Legitimate business need for the information in connection with a business transaction initiated by the target.legitimate-reason-review
: Legitimate business need to review the target's account to determine whether the employee continues to meet the terms of the account.Target
Parameter | Type | Description |
---|---|---|
first_name | string | First name of individual being verified |
last_name | string | Last name of individual being verified |
social_security_number | string | Individual's social security number |
contact_email | string | Best contact email for the individual |
company | Company |
Details about invidual's company |
Company
Parameter | 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. |
When you choose to give a name
instead of an id
, the request may take longer to process.
If you provide id
instead of name
, you will also additionally get turnaround_time
in the response.
Document
An attachment object requires the following:
Parameter | Type | Description |
---|---|---|
filename | string | Name of the file (e.g. "authorization.pdf") |
content | string | Base64 representation of the file |
additional_information
An optional string that can contain information such as date of birth. It must not exceed 1000 characters.
Response Code | Description |
---|---|
201 | The verification request was successfully created. |
400 | There was an error processing your request. See error details for more information. |
The JSON response will look like this:
Field | Type | Description |
---|---|---|
id | string | An identifier of the verification request that was just created |
state | State |
State of the request |
price | Price |
Billing information about how much the verification request will cost once completed |
turnaround_time | TurnaroundTime |
Expected turn around time for the request |
created | string | Creation date of verification request in ISO 8601 format |
State
One of the following:
pending-approval
: The verification request is pending approval by Truework.processing
: The verification request is currently in progress.completed
: The verification request has been completed.Price
Field | Type | Description |
---|---|---|
amount | string | Price of the request in string format |
currency | string | Currency of the price |
Currently we only support USD
as currency. Currency amounts are represented with two decimal precision, e.g. "34.95"
.
TurnaroundTime
We use data from thousands of verification requests to estimate how long a new request will take for a particular company.
For a provided company, upper_bound
and lower_bound
is the time range that most requests will take to complete.
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.
Field | Type | Description |
---|---|---|
upper_bound | int | The estimated upper bound in hours |
lower_bound | int | The estimated lower bound in hours |
1
2
3
4
curl 'https://api.truework.com/verification-requests/?state=pending-approval' \
-X GET \
-H 'Authorization: Bearer myTrueworkToken' \
-H 'Content-Type: application/json'
The above command returns a JSON response like this:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
"results": [
{
"id": "AAAAAAAAQnIAAYd5YHFVOm8PNX2ecFbEjqV__upOKUE8YE_IK2GwSQTP",
"state": "pending-approval",
"created": "2008-09-15T15:53:00Z",
"type": "employment-income",
"price": {
"amount": "39.95",
"currency": "USD"
},
"turnaround_time": {}
},
// ... Further 19 results omitted in example
],
"next": "https://api.truework.com/verification-requests/?offset=20",
"count": 25
}
GET http://api.truework.com/verification-requests/
Use this endpoint to retrieve information about requests.
These parameters can be passed as URL parameters:
Parameter | Type | Description |
---|---|---|
state | string | Filter results by its state. Can be one of pending-approval , processing or completed . |
The JSON response will look like this:
Field | Type | Description |
---|---|---|
results | array of VerificationRequestData |
The list of verification requests filtered as requested. |
next | string | URL for next page of results |
previous | string | URL for previous page of results |
count | int | Total number of results |
The VerificationRequestData
is the same format as the response for creating new requests via a POST on /verification-requests/
as described above.
1
2
3
4
curl 'https://api.truework.com/verification-requests/AAAAAAAAQnIAAYd5YHFVOm8PNX2ecFbEjqV__upOKUE8YE_IK2GwSQTP' \
-X GET \
-H 'Authorization: Bearer myTrueworkToken' \
-H 'Content-Type: application/json'
The above command returns a JSON response like this:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
"id": "AAAAAAAAQnIAAYd5YHFVOm8PNX2ecFbEjqV__upOKUE8YE_IK2GwSQTP",
"state": "completed",
"created": "2008-09-15T15:53:00Z",
"type": "employment-income",
"price": {
"amount": "39.95",
"currency": "USD"
},
"turnaround_time": {},
"permissible_purpose": "credit-application",
"target": {
"company": {
"name": "Future Widget LLC"
},
"first_name": "Joe",
"last_name": "Smith",
"contact_email": "joesmith@example.org"
},
"type": "employment",
"documents": [{
"filename": "employee_authorization.pdf"
}]
}
GET https://api.truework.com/verification-requests/<id>/
Use this endpoint to retrieve information about a specific request.
Parameter | Type | Description |
---|---|---|
id | string | The ID of the request to retrieve. |
Response Code | Description |
---|---|
200 | Successful request for the verification request |
404 | The provided id not found |
The JSON response will look like this:
Field | Type | Description |
---|---|---|
id | string | ID of the created verification request |
state | string | State of the request. One of: pending-approval , processing , completed |
price | Price |
The cost of the completed request |
turnaround_time | TurnaroundTime |
Expected turnaround time for the request |
created | string | Creation date of verification request in ISO 8601 format |
target | Target |
Target employee including the company |
type | string | Type of verification report. One of: employment or employment-income |
permissible_purpose | string | See above for PermissiblePurposeType |
documents | array of Document |
Supporting documents submitted for this request |
additional_information | string | Any supplementary information provided by the verifier regarding the target |
Once a verification request's status is complete
, you will be able to retrieve its report. A report is a subresource of a verification-request
.
There will only be one valid report generated as part of a verification request.
Trying to access the report
resource of a verification-request
when the request is not yet complete
will result in a HTTP 404
.
1
2
3
curl "https://api.truework.com/verification-requests/AAAAAAAAQnIAAYd5YHFVOm8PNX2ecFbEjqV__upOKUE8YE_IK2GwSQTP/report/" \
-X GET \
-H 'Authorization: Bearer myTrueworkToken'
The request above will return a report that looks like:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
{
"created": "2008-09-15T15:53:00Z",
"current_as_of": "2008-09-15T15:53:00Z",
"verification_request": {
"id": "AAAAAAAAQnIAAYd5YHFVOm8PNX2ecFbEjqV__upOKUE8YE_IK2GwSQTP",
"type": "employment-income",
"created": "2008-09-14T9:00:00Z"
},
"employer": {
"name": "Truework Inc",
"address": {
"line_one": "15 Lucerne Street",
"line_two": "Apt 2",
"city": "San Francisco",
"state": "CA",
"country": "US",
"postal_code": "94115"
}
},
"employee": {
"first_name": "First",
"last_name": "Last",
"status": "inactive",
"hired_date": "2017-08-08",
"end_of_employment": "2019-08-08"
"earnings": [
{
"year": 2019,
"base": "35000.00",
"overtime": "200.00",
"commission": "100.25",
"bonus": "500.00",
"total": "35800.25"
},
{
"year": 2018,
"base": "30000.00",
"overtime": "200.00",
"commission": "100.25",
"bonus": "500.00",
"total": "30800.25"
},
{
"year": 2017,
"base": "30000.00",
"overtime": "200.00",
"commission": "100.25",
"bonus": "500.00",
"total": "30800.25"
}
],
"positions": [
{
"title": "current title",
"start_date": "2018-08-08",
"employment_type": "regular-full-time"
},
{
"title": "past title",
"start_date": "2017-08-08",
"end_date": "2019-08-08",
"employment_type": "regular-part-time"
}
],
"salary": {
"gross_pay": "30000.00",
"pay_frequency": "annually",
"hours_per_week": "40"
}
}
}
GET https://api.truework.com/verification-requests/<id>/report/
Parameter | Type | Description |
---|---|---|
id | string | ID of the verification-request |
You can expect the following response codes to be returned:
Response Code | Description |
---|---|
200 | The report was successfully retrieved. |
404 | The report does not exist or you don't have access to it. |
The response will look like:
Parameter | Type | Description |
---|---|---|
created | string | Datetime at which the report was created in ISO 8601 format |
current_as_of | string | Datetime at which the report is up to date in ISO 8601 format |
verification_request | VerificationRequestSnippet |
A snippet of the verification-request resource that this report was generated for |
employer | Employer |
Information about the employer of the employee that is being verified |
employee | Employee |
Information about the employee that is being verified |
VerificationRequestSnippet
Parameter | Type | Description |
---|---|---|
type | string | Type of the verification request |
created | string | Date at which the verification request was created. Returned in ISO 8601 format |
id | string | ID of the verification request |
Employer
Parameter | Type | Description |
---|---|---|
name | string | Name of the employer |
address | Address |
Address of the employer |
Address
Parameter | Type | Description |
---|---|---|
line_one | string | First address line (for example street address) |
line_two | string | Second address line |
city | string | City |
state | string | State |
country | string | Country |
postal_code | string | Postal Code |
Employee
Parameter | Type | Description |
---|---|---|
first_name | string | First name of employee |
last_name | string | Last name of employee |
address | Address |
Address of employee |
status | Status |
Employment status of the employee at this employer |
start_date | string | Date at which employee started work at this employer in ISO 8601 format |
termination_date | string | Date at which employee stopped work at this employer in ISO 8601 format |
termination_reason | string | Reason for termination from employer |
earnings | array of Earnings |
List of earnings found for employee at this employer |
positions | array of Position |
List of positions held by employee at this employer |
salary | Salary |
Current salary of employee at this employer |
Note: earnings
and salary
are only returned for verifications that are of type employment-income
.
Status
One of:
Earnings
Parameter | Type | Description |
---|---|---|
year | int | The year in which the earnings were earned |
base | string | The amount of base pay earned by employee. Returned in money format formatted as a string |
overtime | string | The amount of overtime earned by employee. Returned in money format formatted as a string |
commission | string | The amount of commision earned by employee. Returned in money format formatted as a string |
bonus | string | The amount of bonus earned by employee. Returned in money format formatted as a string |
total | string | The total amount of pay earned by employee. Returned in money format formatted as a string |
Position
Parameter | Type | Description |
---|---|---|
title | string | Title of the employee for this position at employer |
start_date | string | Date at which employee started work in this position in ISO 8601 format |
employment_type | EmploymentType |
Type of employment |
EmploymentType
Salary
Parameter | Type | Description |
---|---|---|
gross_pay | string | Amount paid to employee in gross pay |
pay_frequency | string | Time interval across which the employee is paid gross_pay |
hours_per_week | string | Number of hours worked per week in string format |