API
shell

API Overview

API Base URL

All URLs in the Truework documentation use the following URL as the base:

https://api.truework.com

Authentication

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.

Rate Limits

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.

Resources

Please visit help.truework.com for more information on how verifications are done, turn around times etc...

Error reference sheet

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

Versioning

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

Parameters and Fields

Requests

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.

Responses

Bolded fields will always be present in the response body while other fields may be omitted.

Companies

Search for companies

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
}

Endpoint

GET https://api.truework.com/companies/

Description

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.

Query Parameters

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

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

CompanySearchResult

Field Type Description
id int ID of company
domain string Domain of company
name string Legal name of company

Verifications

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.

Create a new verification request

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"
}

Endpoint

POST https://api.truework.com/verification-requests/

Description

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.

Parameters

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 PermissiblePurposeTypes 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:

PermissiblePurposeType

One of the following:

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.

Responses

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:

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

List requests

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
}

Endpoint

GET http://api.truework.com/verification-requests/

Description

Use this endpoint to retrieve information about requests.

Request Parameters

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.

Response

The JSON response will look like this:

Response

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.

Retrieve a request

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"
  }]
}

Endpoint

GET https://api.truework.com/verification-requests/<id>/

Description

Use this endpoint to retrieve information about a specific request.

Request Parameters

Parameter Type Description
id string The ID of the request to retrieve.

Responses

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

Reports

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.

Retrieve a Report

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"
    }
  }
}

Endpoint

GET https://api.truework.com/verification-requests/<id>/report/

URL Parameters

Parameter Type Description
id string ID of the verification-request

Responses

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
shell