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.
The easiest way to interact with the Truework API is with a first-party API Client.
All URLs in the Truework documentation use the following URL as the base:
https://api.truework.com
1
pip install truework
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
myTrueworkTokenwith your Truework API Key.
1
2
3
require 'truework'
Truework.api_key = 'myTrueworkToken'
Make sure to replace
myTrueworkTokenwith your Truework API Key.
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:
| 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.
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
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'
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.
Bolded fields will always be present in the response body while other fields may be omitted.
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)
GET https://api.truework.com/companies/
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.
| 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 |
| 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 |
| Field | Type | Description |
|---|---|---|
| id | string | id of company |
| name | string | Legal name of company |
| domain | string | Domain of company |
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.
There are different descriptors about a verification request that are commonly used throughout the Verification Request API.
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. |
| 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. |
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. |
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 |
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 })
}
]
)
POST https://api.truework.com/verification-requests/
Creates a new verification request. Returns a JSON object with information including an id of the verification request.
| 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.
| 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 |
| 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 |
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')
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 state |
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
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')
GET https://api.truework.com/verification-requests/<id>/
Retrieves a verification request by id.
| Parameter | Type | Description |
|---|---|---|
| id | string | The id of the desired verification request. |
| 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, cancelled, 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 cancelled 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.
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.
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')
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 | 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.
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
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 |
1
2
3
curl 'https://api.truework.com/title/standardize/?input_title=data+scientist' \
-X GET \
-H 'Authorization: Bearer myTrueworkToken'
GET https://api.truework.com/title/standardize/?input_title=<input_title>
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.
| Parameter | Type | Default | Description |
|---|---|---|---|
| input_title | string | Job title to be standardized |
| Field | Type | Description |
|---|---|---|
| meta | TitlesMeta |
Metadata on the titles taxonomy |
| response | TitlesResponse |
Information about the response from the taxonomy |
| 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.
| Field | Type | Description |
|---|---|---|
| success | boolean | True if the taxonomy successfully standardized the input title |
| results | array of TaxonomyResult |
List of results returned by the taxonomy |
The TitlesResponse simply contains a check for if the standardization was successful and a list containing the results
| Field | Type | Description |
|---|---|---|
| title | Title |
True if the taxonomy successfully standardized the input title |
| confidence | number | Confidence score of the standardized title [0, 1] |
| Field | Type | Description |
|---|---|---|
| id | int | id of the Title |
| name | string | The name of the Title |
| title_family_id | int | the id of the TitleFamily this Title belongs to |
| title_function_id | int | the id of the Function this Title belongs to |
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.
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 |
| 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 |
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.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"
| 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 |