API Overview

The Truework API is a JSON REST API for verifiers to interact with Truework. It allows verifiers to quickly and programmatically create verification requests and retrieve reports. Please visit the help center for more information on Truework's process.

API Clients

The easiest way to interact with the Truework API is with a first-party API Client.

• Ruby SDK

API Base URL

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

https://api.truework.com

1
pip install truework

Authentication

The Truework API uses Bearer Authentication (also known as token authentication). With a token myTrueworkToken, requests to the API can be authenticated by including the token in the HTTP Authorization header.

1
2
$ curl https://api.truework.com \
  -H "Authorization: Bearer myTrueworkToken"

1
truework.API_TOKEN = "myTrueworkToken"

Make sure to replace myTrueworkToken with your Truework API Key.

1
2
3
require 'truework'

Truework.api_key = 'myTrueworkToken'

Make sure to replace myTrueworkToken with your Truework API Key.

Rate Limits

The Truework API safeguards itself from bursts of incoming traffic by employing API limits on each endpoint. Users who send many requests in quick succession may begin to see 429 error responses from the API. We recommend an retrying requests using exponential backoff once receiving a 429 response.

There are two types of limit:

• IP Address: Limits that apply to the IP address that requests are coming from.
• Account: Limits that apply to the overall account.

Rate Type	Limit
IP Address	10 requests per second
Account	10 requests per second

If these limits do not fit your use case, please contact us.

API Response Status Codes

The Truework API 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.

406 - An invalid API version was requested.

429 - The request was not serviced because a rate limit has been exceeded.

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 2019-10-15 (latest). We implicitly version our APIs. If a specific version is not requested in the 'Accept' header, the latest version will be used.

1
2
3
$ curl 'https://api.truework.com/companies/?q=widgets' \
  -X GET \
  -H 'Accept: application/json; version=2019-10-15'

1
truework.API_VERSION = '2019-10-15'

1
Truework.api_version = '2019-10-15'

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 specified in the request.

Responses

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

Companies

Search for companies

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
$ curl 'https://api.truework.com/companies/?q=widgets' \
  -X GET \
  -H 'Authorization: Bearer myTrueworkToken' \
  -H 'Content-Type: application/json'
{
  "results": [
    {
      "id": 57,
      "name": "Bob's Widgets"
    },
    {
      "id": 1234,
      "name": "Future Widget LLC",
      "domain": "futuristic-widgets.example.com"
    },
    {
      "id": 4545,
      "name": "National Pizza With Extras LLC",
      "domain": "widgets-and-pizza.example.com"
    }
  ],
  // ... Further 22 results omitted in example
  "next": "https://api.truework.com/companies/?q=widgets&offset=25",
  "count": 44
}

1
2
3
4
5
>>> response=truework.Company.search("widgets", offset=0, limit=2).auto_paginate()
>>> len(response)
44
>>> list(response.results)
[ TrueworkCompany(57, 'Bob's Widgets, ''), TrueworkCompany(1234, 'Future Widget', 'futuristic-widgets.example.com'), TrueworkCompany(4545 'National Pizza With Extras LLC', 'widgets-and-pizza.example.com', ... ]

1
Truework::Company.list(q: 'International', limit: 10, offset: 0)

Endpoint

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

Description

The company search endpoint can be used to find a company by 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		A string used to find related companies
offset	int	0	Offsets the first company related to the query
limit	int	25	Maximum number of results to return in a single response

Response

Field	Type	Description
results	array of CompanySearchResult	List of company results related to the query
next	string	URL for the next page of results
previous	string	URL for the previous page of results
count	int	Total number of companies related to the query

CompanySearchResult

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

Verification Requests

A verification request is used to retrieve information about an employee's occupation and compensation. The individual requesting the verification is referred to as the verifier; the individual who is being verified is referred to as the target.

Truework offers two types of verification: 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 the target's salary and earnings over the last three years.

Terminology

There are different descriptors about a verification request that are commonly used throughout the Verification Request API.

State

The state helps convey where the verification request is in the Truework process. It will be returned in the JSON objects returned from this endpoint.

state	Description
pending-approval	The initial state after creation. The Truework team has not started working on this request yet.
action-required	A user action is required to continue processing this request. Visit the dashboard for more information.
invalid	Contains invalid information that prevents the verification request from being processed by Truework.
processing	The Truework team is currently working on the verification request.
completed	The verification request has been completed and a report can be found from the reports endpoint.
canceled	Truework denied processing of the request or the verifier no longer wants the request to be processed.

Permissible Purpose

A valid purpose is required for Truework to process the verification request. Throughout the API, this is signified by the permissible_purpose field.

permissible_purpose	Description
child-support	Determine child support payments (available to verifiers that represent a state or local child support enforcement agencies)
credit-application	The target's application for credit.
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.
employee-request	The target has issued the verifier written instruction to obtain this information.
employee-review-or-collection	Performing a review or collection of the target's account.
employment	Employment purposes where the target has given prior written consent.
insurance-underwriting-application	Underwriting insurance in response to the target's application.
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.
risk-assessment	To assess the credit or prepayment risks associated with an existing credit obligation of the target.
subpoena	For a court order or a federal grand jury subpoena.

Type

The verification request type is determined by how much information the verifier wants about the target. Throughout the API, this is signified by the type field.

type	Description
employment	A verification of employment. The verifier wants information about the target's position, start and end dates at a given employer.
employment-income	A verification of income. The verifier wants information about the target's salary and earnings over the last three years in addition to information provided in a VOE

Create a 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
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
$ 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=="
    } ]
  }'

{
  "id": "AAAAAAAAQnIAAYd5YHFVOm8PNX2ecFbEjqV__upOKUE8YE_IK2GwSQTP",
  "created": "2020-01-02T01:46:37.839067Z",
  "type": "employment",
  "permissible_purpose": "risk-assessment",
  "state": "pending-approval",
  "target": {
        "first_name": "Joe",
        "last_name": "Smith",
        "contact_email": "joesmith@example.org",
        "company": {
            "id": "1234",
            "name": "Future Widget LLC"
        }
    },
  "price": {
    "amount": "34.95",
    "currency":"USD"
  },
  "turnaround_time": {
    "upper_bound": "42",
    "lower_bound": "23"
  },
  "documents": [
        {
            "filename": "signed_auth_form.pdf"
        },
        {
            "filename": "verifier_notes.pdf"
        }
    ]
}

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
>>> data = {
...    "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=="
...    } ]
...}
>>> truework.verification_request.VerificationRequest.create(**data)
VerificationRequestAPIResource(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")

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
require 'base64'

Truework::VerificationRequest.create(
  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: Base64.strict_encode64(File.open('/path/to/signed_auth_form.pdf', 'rb').read { |io| io.read })
    },
    {
      filename: 'verifier_notes.pdf',
      content: Base64.strict_encode64(File.open('/path/to/verifier_notes.pdf', 'rb').read { |io| io.read })
    }
  ]
)

Endpoint

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

Description

Creates a new verification request. Returns a JSON object with information including an id of the verification request.

Parameters

Parameter	Type	Description
type	string	Type of verification request.
permissible_purpose	string	Reason for why this verification is being conducted
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

Target

Parameter	Type	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
contact_email	string	Target's email address
company	Company	Details about the target'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 a company name is provided instead of an id, the request may take longer to process. Providing an id is required in order to receive the most accurate turnaround times.

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	The id of the verification request
created	string	Creation date of verification request in ISO 8601 format
type	string	Type of verification report
permissible_purpose	string	Reason for why this verification is being conducted
state	state	State of 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.
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
documents	array of Document	Supporting documentation files provided by the verifier for the verification

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 as strings with two decimal precision, e.g. "34.95".

TurnaroundTime

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.

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	string	The estimated upper bound in hours
lower_bound	string	The estimated lower bound in hours

List Verification Requests

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
$ curl 'https://api.truework.com/verification-requests/?state=pending-approval' \
  -X GET \
  -H 'Authorization: Bearer myTrueworkToken' \
  -H 'Content-Type: application/json'

{
  "results": [
    {
      "id": "AAAAAAAAQnIAAYd5YHFVOm8PNX2ecFbEjqV__upOKUE8YE_IK2GwSQTP",
      "created": "2020-01-02T01:46:37.839067Z",
      "type": "employment",
      "permissible_purpose": "risk-assessment",
      "state": "pending-approval",
      "target": {
            "first_name": "Joe",
            "last_name": "Smith",
            "contact_email": "joesmith@example.org",
            "social_security_number": "***-**-0001",
            "company": {
                "id": "1234",
                "name": "Future Widget LLC"
            }
        },
      "price": {
        "amount": "34.95",
        "currency":"USD"
      },
      "turnaround_time": {
        "upper_bound": "42",
        "lower_bound": "23"
      },
      "documents": [
            {
                "filename": "signed_auth_form.pdf"
            },
            {
                "filename": "verifier_notes.pdf"
            }
        ]
    }
    // ... Further 24 results omitted in example
  ],
  "next": "https://api.truework.com/verification-requests/?offset=25",
  "count": 30
}

1
2
3
4
5
>>> response = truework.verification_request.VerificationRequest.list(offset=0, limit=5)
>>> len(response)
5
>>> list(response)
[VerificationRequest(id='AAAAAAAAQnIAAYd5YHFVOm8PNX2ecFbEjqV__upOKUE8YE_IK2GwSQTP', created='2008-09-15T15:53:00Z', state='pending-approval', price=Price(amount='39.95', currency='USD'), ...]

1
Truework::VerificationRequest.list(state: 'pending-approval')

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 state

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 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
25
26
27
28
29
$ curl 'https://api.truework.com/verification-requests/AAAAAAAAQnIAAYd5YHFVOm8PNX2ecFbEjqV__upOKUE8YE_IK2GwSQTP' \
  -X GET \
  -H 'Authorization: Bearer myTrueworkToken' \
  -H 'Content-Type: application/json'

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

1
2
3
4
>>> verification_id = "AAAAAAAAQnIAAYd5YHFVOm8PNX2ecFbEjqV__upOKUE8YE_IK2GwSQTP"
>>> request = truework.verification_request.VerificationRequest.retrieve(verification_id)
>>> print (request.state)
completed

1
Truework::VerificationRequest.retrieve('AAAAAAAAQnIAAYd5YHFVOm8PNX2ecFbEjqV__upOKUE8YE_IK2GwSQTP')

Endpoint

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

Description

Retrieves a verification request by id.

Request Parameters

Parameter	Type	Description
id	string	The id of the desired verification request.

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 verification request
state	string	State of the request
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	Information about the target employee
type	string	Type of verification report
permissible_purpose	string	Reason for why this verification is being conducted
documents	array of Document	Supporting documents submitted for this request
additional_information	string	Any additional information about the target that can help expedite the completion of the verification request

The initial state will be pending-approval, and will switch to processing once Truework works on the request, but it can switch back to pending-approval when it is pending approval by the target employee.

The states completed, canceled, invalid are terminal states of a verification request. The report is only available when it is in the completed state. A verification request will enter the state canceled when either Truework or you cancel the request. The invalid state indicates that there are issues with the data: We could not locate the employer or the employee at the employer.

Cancel a Verification Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
$ curl 'https://api.truework.com/verification-requests/AAAAAAAAQnIAAYd5YHFVOm8PNX2ecFbEjqV__upOKUE8YE_IK2GwSQTP/cancel/' \
  -X PUT \
  -H 'Authorization: Bearer myTrueworkToken' \
  -H 'Content-Type: application/json' \
  -d '{ \
  "cancellation_reason": "other", \
  "cancellation_details": "Here goes free form text",  \
  }'

  {
    "id": "AAAAAAAAQnIAAYd5YHFVOm8PNX2ecFbEjqV__upOKUE8YE_IK2GwSQTP",
    "state": "canceled",
    "cancellation_reason": "other",
    "cancellation_details": "Details about why this request was canceled.",
    "created": "2008-09-15T15:53:00Z",
    "price": {
      "amount": "0.00",
      "currency": "USD"
    },
    "turnaround_time": {},
  }

1
Truework::VerificationRequest.cancel('AAAAAAAAQnIAAYd5YHFVOm8PNX2ecFbEjqV__upOKUE8YE_IK2GwSQTP', 'other', 'Details about why this request was canceled.')

Endpoint

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

URL Parameters

Parameter	Type	Description
id	string	id of the verification request

Parameter	Type	Description
cancellation_reason	string	Reason for why this verification should be canceled
cancellation_details	string	Free form text on the details, can be blank.

Cancellation Reason

A valid cancellation reason is required for Truework to cancel the verification request.

cancellation_reason	Description
immediate	Can be used to cancel a request directly after submitting, when Truework has not started processing it, yet
high-turnaround-time	The request is taking longer than expected.
competitor	You preferred a competitor for this request.
wrong-info	The request that is submitted contains information that is wrong
other	No other reason in the list fits the cancellation reason

Cancellations are available after 2 days of its creation, except for the reason 'immediate'.

Responses

You can expect the following response codes to be returned:

Response Code	Description
200	The verification request was successfully canceled.
403	The verification request cannot be canceled.

Reports

After Truework successfully processes a verification request, its state will have a state of complete. A report will be available based on the information found during the verification process. There will only be one valid report generated as part of a verification request. If a report is requested when the verification request is not in a completed state, the API will return an HTTP status code of 404.

Retrieve a Report

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
72
73
74
75
76
$ curl "https://api.truework.com/verification-requests/AAAAAAAAQnIAAYd5YHFVOm8PNX2ecFbEjqV__upOKUE8YE_IK2GwSQTP/report/" \
  -X GET \
  -H 'Authorization: Bearer myTrueworkToken'

{
  "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",
    "social_security_number": "***-**-9999",
    "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"
    }
  }
}

1
2
>>> verification_id = "AAAAAAAAQnIAAYd5YHFVOm8PNX2ecFbEjqV__upOKUE8YE_IK2GwSQTP"
>>> report = truework.report.Report.retrieve(verification_id)

1
Truework::Report.retrieve('AAAAAAAAQnIAAYd5YHFVOm8PNX2ecFbEjqV__upOKUE8YE_IK2GwSQTP')

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	string	Current employment status of the employee
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
social_security_number	string	A redacted representation of the employee's social security number in ***-*-XXXX format
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.

Employee Status

There are three employment statuses designated by the status field in Employee:

status	Description
active	The employee is currently employed and working for this employer
inactive	The employee is not employed at this employer anymore
unknown	Truework could not determine the employment status of this employee

Earnings

Parameter	Type	Description
year	string	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 commission 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

• regular-full-time Regular full time
• regular-part-time Regular part time
• contractor Contractor
• other Other or unknown employment type

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

Labs

Standardize a Title

1
2
3
curl 'https://api.truework.com/job-titles/standardize/?input_title=data+scientist' \
  -X GET \
  -H 'Authorization: Bearer myTrueworkToken'

Endpoint

GET https://api.truework.com/job-titles/standardize/?input_title=<input_title>

Description

The title standardization endpoint is used to standardize an input job title via the Truework Titles Taxonomy. The endpoint will respond with your standardized title as well as metadata about your request.

URL Parameters

Parameter	Type	Default	Description
input_title	string		Job title to be standardized

Response

Field	Type	Description
meta	TitlesMeta	Metadata on the titles taxonomy
input	StandardizationInput	the user provided input
success	boolean	True if the taxonomy successfully standardized the input title
results	array of StandardizationResult	List of standardized titles with confidences. Only present if success is true

TitlesMeta

Field	Type	Description
version	string	The version of the Truework Titles Taxonomy being used to process the input

When we make backwards-incompatible changes to the Titles API, we release new dated versions. All requests will utilize the latest version.

StandarizationInput

Field	Type	Description
title	string	The input title provided by the user to the endpoint

StandardizationResult

Field	Type	Description
standardized_title	StandardizedTitle	the standardized title found in the taxonomy
confidence	number	Confidence score of the standardized title [0, 1]

StandardizedTitle

Field	Type	Description
id	int	id of the StandardizedTitle
name	string	The name of the StandardizedTitle
title_family_id	int	the id of the TitleFamily this StandardizedTitle belongs to
title_function_id	int	the id of the Function this Title belongs to

Titles

1
2
3
curl 'https://api.truework.com/job-titles/title/{id}' \
  -X GET \
  -H 'Authorization: Bearer myTrueworkToken'

Endpoint

GET https://api.truework.com/job-titles/title/{id}

Description

The title detail endpoint is used to get more details about a specific Title.

Response Codes

Response Code	Description
200	Successful request for Title details
404	The provided id not found

Response

Field	Type	Description
meta	TitlesMeta	Metadata on the titles taxonomy
title	Title	Standardized job title

TitlesMeta

Field	Type	Description
version	string	The version of the Truework Titles Taxonomy being used to process the input

Title

Field	Type	Description
id	int	the identifier of the found Title
name	string	the standard name of the found Title
title_family_id	int	The id of the Title Family to which the Title belongs
function_id	int	The id of the Function to which the Title belongs.
responsibility_terms	array of strings	The term or terms in the title which contribute to the Responsibility Facet.
seniority_terms	array of strings	The term or terms in the title which contribute to the Seniority Facet.
functionality_terms	array of strings	The term or terms in the title which contribute to the Functionality Facet.

For more information on the terminology and concepts used here, please visit our blogpost on our Job Title Classification System.

Title Families

1
2
3
curl 'https://api.truework.com/job-titles/title-family/{id}' \
  -X GET \
  -H 'Authorization: Bearer myTrueworkToken'

Endpoint

GET https://api.truework.com/job-titles/title-family/{id}

Description

The title detail endpoint is used to get more details about a specific Title Family.

Response Codes

Response Code	Description
200	Successful request for Title Family details
404	The provided id not found

Response

Field	Type	Description
meta	TitlesMeta	Metadata on the titles taxonomy
title_family	TitleFamily	Standardized job title family

TitlesMeta

Field	Type	Description
version	string	The version of the Truework Titles Taxonomy being used to process the input

TitleFamily

Field	Type	Description
id	int	The identifier of the Title Family
name	string	The name of the Title Family
function_id	int	the id of the Function to which the Title Family belongs

Functions

1
2
3
curl 'https://api.truework.com/job-titles/function/{id}' \
  -X GET \
  -H 'Authorization: Bearer myTrueworkToken'

Endpoint

GET https://api.truework.com/job-titles/function/{id}

Description

The title detail endpoint is used to get more details about a specific Function.

Response Codes

Response Code	Description
200	Successful request for Function details
404	The provided id not found

Response

Field	Type	Description
meta	TitlesMeta	Metadata on the titles taxonomy
function	Function	Standardized job function

TitlesMeta

Field	Type	Description
version	string	The version of the Truework Titles Taxonomy being used to process the input

Function

Field	Type	Description
id	int	The identifier of the Function
name	string	The name of the Function

Webhooks

Rather than polling the Truework API for changes, you can arrange for us to send a POST request to a URL you provide whenever certain events occur.

Top-level structure

Webhook requests always have the following fields:

Parameter	Type	Description
hook	hook	Metadata about the webhook
data	data	A payload specific to the event type

hook

Parameter	Type	Description
id	string	The id of the hook itself. You may have several hooks keyed off of the same event
event	string	A unique string which identifies the event which triggered this hook
target	string	The URL to which the hook's payload is sent

Security

• Truework will only send webhook requests over HTTPS.
• Each webhook instance you create is associated with a token. This token is included in all requests made by that hook.
• Tokens can be retrieved from the webhooks section of your API settings.
• You should check the X-Truework-Token header included with each webhook request and reject any request whose token does not correspond to the one shown for that hook on the settings page.

Verification Request Changed

1
2
3
4
5
6
7
8
9
10
11
{
    "hook": {
        "id": "999",
        "event": "verification_request.state.change",
        "target": "https://api.your-company.com/webhook"
    },
    "data": {
        "verification_request_id": "123",
        "state": "completed"
    }
}

We can notify your servers whenever the status of one of your verification requests changes.

The hook.event field will have the value "verification_request.state.change"

data

Parameter	Type	Description
verification_request_id	string	The id of the verification request whose state has changed
state	State	The new state of the verification request