Retrieve an income and employment report for a link
curl --request GET \
--url https://prod.truv.com/v1/links/{link_id}/income/report/ \
--header 'X-Access-Client-Id: <api-key>' \
--header 'X-Access-Secret: <api-key>'import requests
url = "https://prod.truv.com/v1/links/{link_id}/income/report/"
headers = {
"X-Access-Client-Id": "<api-key>",
"X-Access-Secret": "<api-key>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {'X-Access-Client-Id': '<api-key>', 'X-Access-Secret': '<api-key>'}
};
fetch('https://prod.truv.com/v1/links/{link_id}/income/report/', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://prod.truv.com/v1/links/{link_id}/income/report/",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-Access-Client-Id: <api-key>",
"X-Access-Secret: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://prod.truv.com/v1/links/{link_id}/income/report/"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-Access-Client-Id", "<api-key>")
req.Header.Add("X-Access-Secret", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://prod.truv.com/v1/links/{link_id}/income/report/")
.header("X-Access-Client-Id", "<api-key>")
.header("X-Access-Secret", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://prod.truv.com/v1/links/{link_id}/income/report/")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-Access-Client-Id"] = '<api-key>'
request["X-Access-Secret"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"id": "24d7e80942ce4ad58a93f70ce4115f5c",
"status": "new",
"completed_at": "2021-04-06 11:30:00+00:00",
"access_token": "48427a36d43c4d5aa6324bc06c692456",
"tracking_info": "user123456",
"refresh_status": "new",
"employments": [
{
"id": "24d7e80942ce4ad58a93f70ce4115f5c",
"profile": {
"first_name": "John",
"last_name": "Doe",
"id": "48427a36d43c4d5aa6324bc06c692456",
"created_at": "2022-06-07T15:00:00Z",
"updated_at": "2022-06-30T15:00:00Z",
"full_name": "John Doe",
"middle_initials": "K",
"email": "john.doe@example.com",
"ssn": "123456789",
"date_of_birth": "1992-03-03",
"home_address": {
"street": "1 Morgan Ave",
"city": "Los Angeles",
"state": "CA",
"zip": "90210",
"country": "US"
}
},
"company": {
"name": "Facebook Demo",
"address": {
"street": "1 Morgan Ave",
"city": "Los Angeles",
"state": "CA",
"zip": "90210",
"country": "US"
},
"phone": "6503087300",
"ein": "770493581"
},
"income": "70000.00",
"income_unit": "YEARLY",
"pay_rate": "5833.33",
"pay_frequency": "M",
"statements": [
{
"pay_date": "2018-05-31",
"id": "24d7e80942ce4ad58a93f70ce4115f5c",
"check_number": "29205182",
"net_pay": "12915.44",
"net_pay_ytd": "39642.52",
"gross_pay": "18038.33",
"gross_pay_ytd": "55366.65",
"bonus": "100.00",
"commission": "12000.00",
"hours": "173.33",
"basis_of_pay": "S",
"period_start": "2018-05-01",
"period_end": "2018-05-31",
"regular": "5833.33",
"regular_ytd": "29166.65",
"other_pay_ytd": "700.00",
"bonus_ytd": "1000.00",
"commission_ytd": "24000.00",
"overtime": "45.00",
"overtime_ytd": "500.00",
"other_pay": "60.00",
"earnings": [
{
"name": "Regular",
"amount": "5833.33",
"category": "regular",
"rate": null,
"units": null
},
{
"name": "Overtime",
"amount": "45.00",
"category": "overtime",
"rate": "22.50",
"units": "2"
},
{
"name": "Commission",
"amount": "12000.00",
"category": "commission",
"rate": null,
"units": null
},
{
"name": "Bonus",
"amount": "100.00",
"category": "bonus",
"rate": null,
"units": null
},
{
"name": "Spot Award",
"amount": "60.00",
"category": "other_pay",
"rate": null,
"units": null
}
],
"earnings_ytd": [
{
"name": "Regular",
"amount": "29166.65",
"category": "regular",
"rate": null,
"units": null
},
{
"name": "Overtime",
"amount": "500.00",
"category": "overtime",
"rate": null,
"units": null
},
{
"name": "Commission",
"amount": "24000.00",
"category": "commission",
"rate": null,
"units": null
},
{
"name": "Bonus",
"amount": "1000.00",
"category": "bonus",
"rate": null,
"units": null
},
{
"name": "Spot Award",
"amount": "700.00",
"category": "other_pay",
"rate": null,
"units": null
}
],
"deductions": [
{
"name": "Federal Income Tax",
"amount": "2705.75",
"category": "federal"
},
{
"name": "Social Security Tax",
"amount": "1118.38",
"category": "socialsec"
},
{
"name": "Medicare Tax",
"amount": "261.56",
"category": "medicare"
},
{
"name": "VA State Income Tax",
"amount": "1037.20",
"category": "state"
}
],
"deductions_ytd": [
{
"name": "Federal Income Tax",
"amount": "8305.00",
"category": "federal"
},
{
"name": "Social Security Tax",
"amount": "3432.73",
"category": "socialsec"
},
{
"name": "Medicare Tax",
"amount": "802.82",
"category": "medicare"
},
{
"name": "VA State Income Tax",
"amount": "3183.58",
"category": "state"
}
],
"md5sum": "03639d6a6624f69a54a88ea90bd25e9d",
"file": "https://cdn.truv.com/paystub_sample.pdf",
"derived_fields": [
"basis_of_pay"
],
"missing_data_fields": [
"earnings_ytd"
]
}
],
"annual_income_summary": [
{
"id": "24d7e80942ce4ad58a93f70ce4115f5c",
"year": 2018,
"regular": "29166.65",
"bonus": "1000.00",
"commission": "24000.00",
"overtime": "500.00",
"other_pay": "700.00",
"net_pay": "39642.52",
"gross_pay": "55366.65"
}
],
"bank_accounts": [
{
"account_number": "1234567890",
"routing_number": "123456789",
"account_name": "My Bank",
"account_type": "C",
"deposit_type": "A",
"deposit_value": "200.00",
"bank_name": "TD Bank"
}
],
"w2s": [
{
"file": "https://cdn.truv.com/W2_sample.pdf",
"md5sum": "f65e30c39124ad707ac4b3aeaee923a7",
"year": 2020,
"wages": "70000.00",
"federal_tax": "5830.87",
"social_security_wages": "70000.00",
"social_security_tax": "4340.00",
"medicare_wages": "70000.00",
"medicare_tax": "1015.00",
"gross_pay": "70000.00"
}
],
"is_active": false,
"job_title": "PR associate",
"job_type": "F",
"start_date": "2018-01-01",
"original_hire_date": "2017-06-21",
"end_date": "2023-12-25",
"external_last_updated": "2023-12-25",
"dates_from_statements": false,
"derived_fields": [
"is_active"
],
"missing_data_fields": [
"w2s"
],
"manager_name": "Jenny McDouglas"
}
],
"provider": "adp",
"finished_at": "2021-04-06T11:30:00Z",
"is_suspicious": true,
"fraud_reasons": [
{
"code": "editing_software_detected",
"message": "Document metadata identifies editing software.",
"severity": "high",
"document_ids": [
"d1f3a6e0b1c24f6c9b3e2a7d5c8e9f01"
],
"uploaded_file_ids": [
"9ac0b2d4e6f84a1c8e3b5d7f9a1c3e5b"
],
"details": {
"software": [
"Adobe Photoshop 25.0 (Windows)"
]
},
"task_id": "48427a36d43c4d5aa6324bc06c692456",
"created_at": "2026-10-20T14:03:11Z"
}
],
"pdf_report": "https://cdn.truv.com/report.pdf",
"data_source": "payroll"
}{
"error": {
"code": "authentication_failed",
"message": "No such token"
}
}{
"error": {
"code": "not_authenticated",
"message": "Authentication credentials were not provided."
}
}{
"error": {
"code": "not_found",
"message": "Requested object not found."
}
}Link Income and Employment Report
Retrieve an income and employment report for a link
The endpoint returns the VOIE report for a link
GET
/
v1
/
links
/
{link_id}
/
income
/
report
/
Retrieve an income and employment report for a link
curl --request GET \
--url https://prod.truv.com/v1/links/{link_id}/income/report/ \
--header 'X-Access-Client-Id: <api-key>' \
--header 'X-Access-Secret: <api-key>'import requests
url = "https://prod.truv.com/v1/links/{link_id}/income/report/"
headers = {
"X-Access-Client-Id": "<api-key>",
"X-Access-Secret": "<api-key>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {'X-Access-Client-Id': '<api-key>', 'X-Access-Secret': '<api-key>'}
};
fetch('https://prod.truv.com/v1/links/{link_id}/income/report/', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://prod.truv.com/v1/links/{link_id}/income/report/",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-Access-Client-Id: <api-key>",
"X-Access-Secret: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://prod.truv.com/v1/links/{link_id}/income/report/"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-Access-Client-Id", "<api-key>")
req.Header.Add("X-Access-Secret", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://prod.truv.com/v1/links/{link_id}/income/report/")
.header("X-Access-Client-Id", "<api-key>")
.header("X-Access-Secret", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://prod.truv.com/v1/links/{link_id}/income/report/")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-Access-Client-Id"] = '<api-key>'
request["X-Access-Secret"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"id": "24d7e80942ce4ad58a93f70ce4115f5c",
"status": "new",
"completed_at": "2021-04-06 11:30:00+00:00",
"access_token": "48427a36d43c4d5aa6324bc06c692456",
"tracking_info": "user123456",
"refresh_status": "new",
"employments": [
{
"id": "24d7e80942ce4ad58a93f70ce4115f5c",
"profile": {
"first_name": "John",
"last_name": "Doe",
"id": "48427a36d43c4d5aa6324bc06c692456",
"created_at": "2022-06-07T15:00:00Z",
"updated_at": "2022-06-30T15:00:00Z",
"full_name": "John Doe",
"middle_initials": "K",
"email": "john.doe@example.com",
"ssn": "123456789",
"date_of_birth": "1992-03-03",
"home_address": {
"street": "1 Morgan Ave",
"city": "Los Angeles",
"state": "CA",
"zip": "90210",
"country": "US"
}
},
"company": {
"name": "Facebook Demo",
"address": {
"street": "1 Morgan Ave",
"city": "Los Angeles",
"state": "CA",
"zip": "90210",
"country": "US"
},
"phone": "6503087300",
"ein": "770493581"
},
"income": "70000.00",
"income_unit": "YEARLY",
"pay_rate": "5833.33",
"pay_frequency": "M",
"statements": [
{
"pay_date": "2018-05-31",
"id": "24d7e80942ce4ad58a93f70ce4115f5c",
"check_number": "29205182",
"net_pay": "12915.44",
"net_pay_ytd": "39642.52",
"gross_pay": "18038.33",
"gross_pay_ytd": "55366.65",
"bonus": "100.00",
"commission": "12000.00",
"hours": "173.33",
"basis_of_pay": "S",
"period_start": "2018-05-01",
"period_end": "2018-05-31",
"regular": "5833.33",
"regular_ytd": "29166.65",
"other_pay_ytd": "700.00",
"bonus_ytd": "1000.00",
"commission_ytd": "24000.00",
"overtime": "45.00",
"overtime_ytd": "500.00",
"other_pay": "60.00",
"earnings": [
{
"name": "Regular",
"amount": "5833.33",
"category": "regular",
"rate": null,
"units": null
},
{
"name": "Overtime",
"amount": "45.00",
"category": "overtime",
"rate": "22.50",
"units": "2"
},
{
"name": "Commission",
"amount": "12000.00",
"category": "commission",
"rate": null,
"units": null
},
{
"name": "Bonus",
"amount": "100.00",
"category": "bonus",
"rate": null,
"units": null
},
{
"name": "Spot Award",
"amount": "60.00",
"category": "other_pay",
"rate": null,
"units": null
}
],
"earnings_ytd": [
{
"name": "Regular",
"amount": "29166.65",
"category": "regular",
"rate": null,
"units": null
},
{
"name": "Overtime",
"amount": "500.00",
"category": "overtime",
"rate": null,
"units": null
},
{
"name": "Commission",
"amount": "24000.00",
"category": "commission",
"rate": null,
"units": null
},
{
"name": "Bonus",
"amount": "1000.00",
"category": "bonus",
"rate": null,
"units": null
},
{
"name": "Spot Award",
"amount": "700.00",
"category": "other_pay",
"rate": null,
"units": null
}
],
"deductions": [
{
"name": "Federal Income Tax",
"amount": "2705.75",
"category": "federal"
},
{
"name": "Social Security Tax",
"amount": "1118.38",
"category": "socialsec"
},
{
"name": "Medicare Tax",
"amount": "261.56",
"category": "medicare"
},
{
"name": "VA State Income Tax",
"amount": "1037.20",
"category": "state"
}
],
"deductions_ytd": [
{
"name": "Federal Income Tax",
"amount": "8305.00",
"category": "federal"
},
{
"name": "Social Security Tax",
"amount": "3432.73",
"category": "socialsec"
},
{
"name": "Medicare Tax",
"amount": "802.82",
"category": "medicare"
},
{
"name": "VA State Income Tax",
"amount": "3183.58",
"category": "state"
}
],
"md5sum": "03639d6a6624f69a54a88ea90bd25e9d",
"file": "https://cdn.truv.com/paystub_sample.pdf",
"derived_fields": [
"basis_of_pay"
],
"missing_data_fields": [
"earnings_ytd"
]
}
],
"annual_income_summary": [
{
"id": "24d7e80942ce4ad58a93f70ce4115f5c",
"year": 2018,
"regular": "29166.65",
"bonus": "1000.00",
"commission": "24000.00",
"overtime": "500.00",
"other_pay": "700.00",
"net_pay": "39642.52",
"gross_pay": "55366.65"
}
],
"bank_accounts": [
{
"account_number": "1234567890",
"routing_number": "123456789",
"account_name": "My Bank",
"account_type": "C",
"deposit_type": "A",
"deposit_value": "200.00",
"bank_name": "TD Bank"
}
],
"w2s": [
{
"file": "https://cdn.truv.com/W2_sample.pdf",
"md5sum": "f65e30c39124ad707ac4b3aeaee923a7",
"year": 2020,
"wages": "70000.00",
"federal_tax": "5830.87",
"social_security_wages": "70000.00",
"social_security_tax": "4340.00",
"medicare_wages": "70000.00",
"medicare_tax": "1015.00",
"gross_pay": "70000.00"
}
],
"is_active": false,
"job_title": "PR associate",
"job_type": "F",
"start_date": "2018-01-01",
"original_hire_date": "2017-06-21",
"end_date": "2023-12-25",
"external_last_updated": "2023-12-25",
"dates_from_statements": false,
"derived_fields": [
"is_active"
],
"missing_data_fields": [
"w2s"
],
"manager_name": "Jenny McDouglas"
}
],
"provider": "adp",
"finished_at": "2021-04-06T11:30:00Z",
"is_suspicious": true,
"fraud_reasons": [
{
"code": "editing_software_detected",
"message": "Document metadata identifies editing software.",
"severity": "high",
"document_ids": [
"d1f3a6e0b1c24f6c9b3e2a7d5c8e9f01"
],
"uploaded_file_ids": [
"9ac0b2d4e6f84a1c8e3b5d7f9a1c3e5b"
],
"details": {
"software": [
"Adobe Photoshop 25.0 (Windows)"
]
},
"task_id": "48427a36d43c4d5aa6324bc06c692456",
"created_at": "2026-10-20T14:03:11Z"
}
],
"pdf_report": "https://cdn.truv.com/report.pdf",
"data_source": "payroll"
}{
"error": {
"code": "authentication_failed",
"message": "No such token"
}
}{
"error": {
"code": "not_authenticated",
"message": "Authentication credentials were not provided."
}
}{
"error": {
"code": "not_found",
"message": "Requested object not found."
}
}Authorizations
Client ID
Client Access Key
Path Parameters
Query Parameters
Set to true to include fraud_reasons in the response. The field is omitted by default.
Response
Data for the income verification
Unique ID
Maximum string length:
32Example:
"24d7e80942ce4ad58a93f70ce4115f5c"
Example:
"new"
Time when report was completed (Deprecated, invalid datetime format)
Example:
"2021-04-06 11:30:00+00:00"
Access token for a Link to payroll provider
Maximum string length:
32Example:
"48427a36d43c4d5aa6324bc06c692456"
Any information passed to the Truv Bridge from a partner
Maximum string length:
255Example:
"user123456"
Status of the most recent refresh task
Example:
"new"
List of employments received from a payroll provider
Show child attributes
Show child attributes
Payroll provider name
Maximum string length:
64Example:
"adp"
Time when report was finished
Example:
"2021-04-06T11:30:00Z"
Flag to indicate if the data from the source is suspicious. E.g. fraud detected in uploaded documents or SSN of the user does not match with the data
Findings recorded for this link and its tasks. Included only when show_fraud_reasons=true. An empty array means no findings are available for this response.
Show child attributes
Show child attributes
Verification report in PDF format
Example:
"https://cdn.truv.com/report.pdf"
Source of data: crawler - payroll provider parsing, docs - user uploaded documents
Available options:
payroll, docs, financial_accounts Example:
"payroll"
Was this page helpful?