API
curl python ruby

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.

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:

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

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

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

Normalize a Title

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

Endpoint

GET https://api.truework.com/title/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
response TitlesResponse Information about the response from the taxonomy

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.

TitlesResponse

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

TaxonomyResult

Field Type Description
title Title True if the taxonomy successfully standardized the input title
confidence number Confidence score of the standardized title [0, 1]

Title

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

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

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