Attributes

The table below has the values for Tax Document fields.

Attribute	Type	Description
id	string	Unique identifier
document_type	string	Type of document. One of: W2, F1099, F1040
document_subtype	string, null	Subtype of document (nullable). One of: F1099_B, F1099_DIV, F1099_G, F1099_INT, F1099_K, F1099_MISC, F1099_NEC, F1099_R, F_SSA1099
file	uri	Link to tax document file, format is specified in the content-type (up to 2048 characters long)
md5sum	string	MD5 hash value computed based on file content
year	integer	Tax document year
fields	object, null	Extracted form data, returned only by Retrieve a tax document. The key set depends on the document type and on where the document came from — see Where the data comes from

Endpoint

The link below is the reference for the available Tax Document endpoint.

Listing returns an array without fields:

[
  {
    "id": "24d7e80942ce4ad58a93f70ce4115f5c",
    "document_type": "W2",
    "document_subtype": null,
    "file": "https://prod.truv.com/v1/permalink/w2.pdf",
    "md5sum": "f65e30c39124ad707ac4b3aeaee923a7",
    "year": 2024
  }
]

Retrieving a single document adds fields:

{
  "id": "24d7e80942ce4ad58a93f70ce4115f5c",
  "document_type": "W2",
  "document_subtype": null,
  "file": "https://prod.truv.com/v1/permalink/w2.pdf",
  "md5sum": "f65e30c39124ad707ac4b3aeaee923a7",
  "year": 2024,
  "fields": {...} // see below by source and form type
}

Where the data comes from

Tax documents reach Truv three ways, and each one extracts a different amount of the form. The link’s data_source tells you which path produced a document, so read it before you read fields.

`data_source`	How documents arrive	Document types	What `fields` covers
`docs`	Document upload — your user or your team sends files to Truv	`W2`, `F1099`, `F1040`	The full form, including W-2 Box 12, Box 13, and second-state data, the income boxes of every supported 1099 variant, and the complete 1040 package with its schedules
`payroll`	Payroll connection — Truv pulls W-2s from the payroll provider during full parse	`W2`	Boxes 1–7 and `gross_pay`
`tax`	Tax software connection	`F1040`	The file only — `fields` is `null`

Treat every key as optional and branch on data_source. Each section below lists what that source returns.

Reading `fields`

These rules hold for every document type and every source.

Keys mirror the boxes and lines of the IRS form.
Monetary amounts are decimal strings.
Blank boxes are omitted. A key is present with a zero value only when the form itself shows a zero.
Checkboxes are returned as the string "yes" when checked, and omitted when unchecked.
Names, SSNs, and employer details are not in fields, except a 1099 recipient’s business name in recipient_business_name. They populate the profile and company objects on the income report.
The w2s array on an income report is a summary: wages, federal_tax, social_security_wages, social_security_tax, medicare_wages, medicare_tax, and gross_pay. Retrieve the tax document itself for everything below.

W-2 from uploaded documents

data_source: docs, document_type: W2. Truv reads the whole form, including Box 12 codes, Box 13 checkboxes, and multi-state data.

Wage and tax boxes

Field	Box	Description
control_number	d	Employer’s control number (string)
wages	1	Wages, tips, other compensation
federal_tax	2	Federal income tax withheld
social_security_wages	3	Social security wages
social_security_tax	4	Social security tax withheld
medicare_wages	5	Medicare wages and tips
medicare_tax	6	Medicare tax withheld
social_security_tips	7	Social security tips
allocated_tips	8	Allocated tips
dependent_care_benefits	10	Dependent care benefits
nonqualified_plans	11	Nonqualified plans
gross_pay	—	Gross pay. Not a W-2 box — returned when the file shows it.

Box 12 codes

Each of the four Box 12 slots returns a letter code and an amount.

Field	Box	Description
a_code, a_value	12a	Code letter (`D`, `DD`, `W`, `AA`, …) and amount
b_code, b_value	12b	Code letter and amount
c_code, c_value	12c	Code letter and amount
d_code, d_value	12d	Code letter and amount

Box 13 checkboxes

Field	Box	Description
statutory_employee	13	`"yes"` when checked
retirement_plan	13	`"yes"` when checked
third_party_sick_pay	13	`"yes"` when checked

State and local boxes

An uploaded W-2 carries up to two states, and up to two localities per state. Each field is returned under a key with no suffix and under an indexed key:

The key with no suffix is always the first row. state holds the same value as state_1, and locality_name holds the same value as locality_name_1_1.
State keys are indexed _1 for the first state and _2 for the second.
Locality keys are indexed _{state}_{locality}, so _1_2 is the second locality of the first state and _2_1 is the first locality of the second state.
A second state or locality has no form without a suffix. It appears only as _2, _1_2, _2_1, or _2_2.

State keys (Boxes 15–17)

Field	Box	Description	Keys returned
state	15	Two-letter state code	`state`, `state_1`, `state_2`
employer_state_id_number	15	Employer’s state ID number	`employer_state_id_number`, `employer_state_id_number_1`, `employer_state_id_number_2`
state_wages_tips	16	State wages, tips, etc.	`state_wages_tips`, `state_wages_tips_1`, `state_wages_tips_2`
state_income_tax	17	State income tax	`state_income_tax`, `state_income_tax_1`, `state_income_tax_2`

Locality keys (Boxes 18–20)

Field	Box	Description	Keys returned
local_wages_tips	18	Local wages, tips, etc.	`local_wages_tips`, `local_wages_tips_1_1`, `local_wages_tips_1_2`, `local_wages_tips_2_1`, `local_wages_tips_2_2`
local_income_tax	19	Local income tax	`local_income_tax`, `local_income_tax_1_1`, `local_income_tax_1_2`, `local_income_tax_2_1`, `local_income_tax_2_2`
locality_name	20	Locality name	`locality_name`, `locality_name_1_1`, `locality_name_1_2`, `locality_name_2_1`, `locality_name_2_2`

Example

A W-2 with one state and one locality.

{
  "control_number": "0001234",
  "wages": "56269.25",
  "federal_tax": "4102.75",
  "social_security_wages": "58805.40",
  "social_security_tax": "3645.93",
  "medicare_wages": "58805.40",
  "medicare_tax": "852.68",
  "a_code": "D",
  "a_value": "2536.00",
  "b_code": "DD",
  "b_value": "9174.00",
  "retirement_plan": "yes",
  "state": "OH",
  "state_1": "OH",
  "employer_state_id_number": "51-123456",
  "employer_state_id_number_1": "51-123456",
  "state_wages_tips": "58805.40",
  "state_wages_tips_1": "58805.40",
  "state_income_tax": "1978.14",
  "state_income_tax_1": "1978.14",
  "locality_name": "COLUMBUS",
  "locality_name_1_1": "COLUMBUS",
  "local_wages_tips": "58805.40",
  "local_wages_tips_1_1": "58805.40",
  "local_income_tax": "1470.13",
  "local_income_tax_1_1": "1470.13"
}

W-2 from a payroll connection

data_source: payroll, document_type: W2. Truv reads the numbered wage boxes from the W-2 the provider supplies. Upload the document for the full form.

Field	Box	Description
wages	1	Wages, tips, other compensation
federal_tax	2	Federal income tax withheld
social_security_wages	3	Social security wages
social_security_tax	4	Social security tax withheld
medicare_wages	5	Medicare wages and tips
medicare_tax	6	Medicare tax withheld
social_security_tips	7	Social security tips
gross_pay	—	Gross pay. Not a W-2 box — returned when the file shows it.

{
  "wages": "56269.25",
  "federal_tax": "4102.75",
  "social_security_wages": "58805.40",
  "social_security_tax": "3645.93",
  "medicare_wages": "58805.40",
  "medicare_tax": "852.68",
  "gross_pay": "58805.40"
}

1099 from uploaded documents

data_source: docs, document_type: F1099. 1099s reach Truv only through document upload. Every variant returns the same flat set of keys under fields. Only the boxes that exist on that variant and carry a value are present.

The keys below are returned for 1099s uploaded on or after November 1, 2026.

Form variant

document_subtype comes from the form’s own masthead, not from the subtype selected at upload. It is null for a 1099 variant outside the list below, such as 1099-SA or 1099-OID. When the masthead cannot be read, the subtype selected at upload is kept.

`document_subtype`	Form
`F1099_NEC`	1099-NEC
`F1099_MISC`	1099-MISC
`F1099_INT`	1099-INT
`F1099_DIV`	1099-DIV
`F1099_G`	1099-G
`F1099_R`	1099-R
`F1099_K`	1099-K
`F1099_B`	1099-B
`F_SSA1099`	SSA-1099

A consolidated brokerage statement that combines 1099-DIV, 1099-INT, and 1099-B sections is stored as one tax document with fields from every section and a single document_subtype. Inspect the keys present in fields rather than treating document_subtype as a complete list of the variants on the form.

Fields on every variant

Field	Description
form_number	Form identifier as printed, for example `1099-NEC` (string)
account_number	Payer’s account number for the recipient (string)
federal_income_tax_withheld	Federal income tax withheld
recipient_business_name	Recipient’s business name when the recipient box names an LLC, corporation, partnership, trust, estate, or DBA (string). A person’s DBA, such as `JOHN SMITH DBA ACME LOGISTICS`, returns the business name here and the person’s name on the profile. Omitted when the form prints no business name

Income boxes by variant

Field	Form	Box	Description
nonemployee_compensation	1099-NEC	1	Nonemployee compensation
rents	1099-MISC	1	Rents
royalties	1099-MISC	2	Royalties
other_income	1099-MISC	3	Other income
interest_income	1099-INT	1	Interest income
total_ordinary_dividends	1099-DIV	1a	Total ordinary dividends
qualified_dividends	1099-DIV	1b	Qualified dividends
unemployment_compensation	1099-G	1	Unemployment compensation
gross_distribution	1099-R	1	Gross distribution
taxable_amount	1099-R	2a	Taxable amount
total_distribution	1099-R	2b	`"yes"` when the total distribution box is checked
distribution_code	1099-R	7	Distribution code (string)
gross_amount	1099-K	1a	Gross amount of payment card and third-party network transactions
proceeds	1099-B	—	Total proceeds
benefits_paid	SSA-1099	3	Benefits paid
benefits_repaid	SSA-1099	4	Benefits repaid to SSA
net_benefits	SSA-1099	5	Net benefits
claim_number	SSA-1099	8	Claim number (string)

State boxes

A 1099 carries up to two state rows. They follow the same scheme as the W-2 state keys: the key with no suffix repeats the first row, _1 is the first state, and _2 is the second state, which has no form without a suffix.

Field	Description	Keys returned
state	Two-letter state code	`state`, `state_1`, `state_2`
state_identification_no	Payer’s state identification number	`state_identification_no`, `state_identification_no_1`, `state_identification_no_2`
state_income	State income	`state_income`, `state_income_1`, `state_income_2`
state_tax_withheld	State tax withheld	`state_tax_withheld`, `state_tax_withheld_1`, `state_tax_withheld_2`

Recipient and payer

The recipient’s personal name, TIN, and address are not in fields. They populate the profile on the income report, as for other tax documents. A business name printed in the recipient box, whether on its own or as a person’s DBA, is returned in recipient_business_name. A 1099 is linked to an employment when the form names both a recipient person and a payer. The payer’s name, TIN, and address become that employment’s company. When either is missing, the 1099 is stored without an employment, and its fields are available only from Retrieve a tax document.

Example

A 1099-NEC with one state row. The number of decimal places in an amount varies, so parse amounts as numbers rather than comparing strings: a whole-dollar amount can arrive as "0.0" or "0.00".

{
  "form_number": "1099-NEC",
  "account_number": "8353DF54",
  "nonemployee_compensation": "11955.0",
  "federal_income_tax_withheld": "0.0",
  "state": "NJ",
  "state_1": "NJ",
  "state_identification_no": "123-456-789/000",
  "state_identification_no_1": "123-456-789/000",
  "state_income": "11955.0",
  "state_income_1": "11955.0"
}

1040 from uploaded documents

data_source: docs, document_type: F1040. A 1040 is read as a package: the main form plus any attached Schedule 1, Schedule C, Form 4562, and Form 4684. Each attachment type is an array under fields, because a return can carry several of them.

A 1040 that arrives through a tax software connection (data_source: tax) is stored as a file with fields: null. Line-level extraction requires the document upload path.

Each Schedule C becomes an employment. Truv creates one employment per Schedule C business on the return: company name from Line C, EIN from Line D, address from Line E, job_title from Line A, and start_date from Line H. Sole proprietors who leave Line C blank get the taxpayer’s own name as the company name. The 1040 document is linked to each of those employments, so self-employed income appears in the income report next to payroll-sourced employments. A return with no Schedule C is stored without an employment.

On a joint return, Truv matches the applicant to the primary filer or the spouse — by SSN first, then by name — and returns only that taxpayer’s schedules. A schedule that carries no owner information is treated as shared and included.

Form 1040 fields

Field	Line	Description
form_variant	—	Variant found on the form: `1040`, `1040-SR`, `1040-NR`, `1040-SS`
w2_wages	1a	Total amount from Form(s) W-2, box 1
wages_salaries_tips	1z	Total wages, salaries, and tips
qualified_dividends	3a	Qualified dividends
ordinary_dividends	3b	Ordinary dividends
ira_distributions_total	4a	IRA distributions
ira_distributions_taxable	4b	Taxable IRA distributions
pension_and_annuities	5a	Pensions and annuities
pension_and_annuities_taxable	5b	Taxable pensions and annuities
social_security_benefits	6a	Social security benefits
social_security_benefits_taxable	6b	Taxable social security benefits
capital_gain	7	Capital gain or loss
other_income	8	Other income, from Schedule 1 line 10
total_income	9	Total income
adjusted_gross_income	11	Adjusted gross income
standard_or_itemized_deduction	12	Standard or itemized deductions
taxable_income	15	Taxable income
total_credits	21	Total nonrefundable credits
total_tax	24	Total tax
federal_income_tax_withheld	25d	Total federal income tax withheld
total_payments	33	Total payments
refund_amount	34	Overpayment (refund)
amount_owed	37	Amount owed
preparer_name	—	Paid tax preparer’s printed name (string)
preparer_ptin	—	Paid tax preparer’s PTIN (string)

Attached schedules and forms

Objects in these arrays may also carry pages — the page range the form occupies in the uploaded file, for example "3-4".

schedule_1 — Additional Income and Adjustments

Field	Line	Description
taxable_refunds	1	Taxable refunds, credits, or offsets of state and local income taxes
alimony_received	2a	Alimony received
business_income_loss	3	Business income or loss, from Schedule C
other_gains_losses	4	Other gains or losses
rental_re_royalties_partnerships	5	Rental real estate, royalties, partnerships, S corps, trusts
unemployment_compensation	7	Unemployment compensation
net_operating_loss	8a	Net operating loss deduction
gambling_income	8b	Gambling income
total_other_income	9	Total other income
total_additional_income	10	Total additional income. Flows to 1040 line 8.
educator_expenses	11	Educator expenses
hsa_deduction	13	HSA deduction
ira_deduction	20	IRA deduction
student_loan_interest	21	Student loan interest deduction
total_adjustments	26	Total adjustments. Flows to 1040 line 10.

schedule_c — Profit or Loss from Business

Field	Line	Description
principal_business_or_profession	A	Principal business or profession (string)
business_activity_code	B	Principal business code (string)
business_name	C	Business name (string)
ein	D	Employer ID number, 9 digits, hyphenated or not as printed on the form (string)
last_four_digits_employer_identifier	D	Last four digits of the EIN (string)
business_street	E	Business street address (string)
business_city	E	Business city (string)
business_state	E	Business state, two-letter code (string)
business_zip	E	Business ZIP code (string)
accounting_method	F	Cash, Accrual, or Other (string)
business_started_acquired	H	Date the business started or was acquired (string)
gross_receipts_or_sales	1	Gross receipts or sales
returns_and_allowances	2	Returns and allowances
tentative_gross_profit	3	Line 1 minus line 2
cost_of_goods_sold	4	Cost of goods sold
gross_profit	5	Gross profit
other_income_loss	6	Other income
gross_income	7	Total income
advertising	8	Advertising
car_truck_expenses	9	Car and truck expenses
commissions_and_fees	10	Commissions and fees
depletion	12	Depletion
depreciation	13	Depreciation and section 179 expense
insurance_other_than_health	15	Insurance other than health
mortgage_paid_to_banks	16a	Mortgage interest paid to banks
office_expense	18	Office expense
rent_vehicle_machinery_equip	20a	Rent or lease of vehicles, machinery, and equipment
deductible_meals	24b	Deductible meals
non_deductible_meals	24b	Non-deductible meals
wages_less_employment_credits	26	Wages less employment credits
total_other_expenses	27a	Other expenses, from Part V line 48
total_expenses_before_home_use	28	Total expenses before business use of home
tentative_profit_loss	29	Tentative profit or loss
business_use_home	30	Expenses for business use of home
net_profit_loss	31	Net profit or loss. Flows to Schedule 1 line 3.
vehicle_service_start_date	43	Date the vehicle was placed in service (string)
business_mileage	44a	Business miles driven
amortization	Part V	Amortization

form_4562 — Depreciation and Amortization

Field	Line	Description
business_activity_relation	—	The “business or activity to which this form relates” header (string)
section_179_deduction	12	Section 179 expense deduction
special_depreciation_allowance	14	Special depreciation allowance
macrs_depreciation	17	MACRS depreciation for assets placed in service in prior years
total_depreciation_deduction	22	Total depreciation
depreciation_deduction	28	Total listed property depreciation deduction
listed_property_business_miles	30	Total business and investment miles for the year
total_amortization	44	Total amortization

form_4684 — Casualties and Thefts

Field	Line	Description
property_description	19	Description of properties (string)
short_term_gain_loss_nonincome	31	Section B short-term gain or loss, non-income producing property
short_term_loss_income	32	Section B short-term loss, income-producing property
long_term_gain	36	Section B long-term gain
long_term_loss	37	Section B long-term loss
total_gain_loss	38a, 38b	Total gain or loss

Example

A return with one Schedule C business, trimmed to a few lines per form.

{
  "form_variant": "1040",
  "w2_wages": "48000.00",
  "wages_salaries_tips": "48000.00",
  "total_income": "75000.00",
  "adjusted_gross_income": "72500.00",
  "taxable_income": "58650.00",
  "total_tax": "8420.00",
  "federal_income_tax_withheld": "9100.00",
  "refund_amount": "680.00",
  "preparer_name": "Alice Nguyen",
  "preparer_ptin": "P01234567",
  "schedule_1": [
    {
      "business_income_loss": "27000.00",
      "total_additional_income": "27000.00",
      "total_adjustments": "2500.00",
      "pages": "3"
    }
  ],
  "schedule_c": [
    {
      "principal_business_or_profession": "Graphic design",
      "business_activity_code": "541430",
      "business_name": "Smith Design LLC",
      "ein": "12-3456789",
      "business_street": "100 Business Ave",
      "business_city": "Columbus",
      "business_state": "OH",
      "business_zip": "43004",
      "accounting_method": "Cash",
      "business_started_acquired": "2019-04-01",
      "gross_receipts_or_sales": "50000.00",
      "gross_income": "50000.00",
      "total_expenses_before_home_use": "23000.00",
      "net_profit_loss": "27000.00",
      "pages": "4-5"
    }
  ]
}

API Reference

Platform

Income & Employment

Financial Accounts

Document Processing

Direct Deposit Switch

Insurance Verification

The Tax Documents object

Attributes

Endpoint

Where the data comes from

Reading `fields`

W-2 from uploaded documents

Wage and tax boxes

Box 12 codes

Box 13 checkboxes

State and local boxes

State keys (Boxes 15–17)

Locality keys (Boxes 18–20)

Example

W-2 from a payroll connection

1099 from uploaded documents

Form variant

Fields on every variant

Income boxes by variant

State boxes

Recipient and payer

Example

1040 from uploaded documents

Form 1040 fields

Attached schedules and forms

Example

Attributes

Endpoint

Where the data comes from

Reading fields

W-2 from uploaded documents

Wage and tax boxes

Box 12 codes

Box 13 checkboxes

State and local boxes

State keys (Boxes 15–17)

Locality keys (Boxes 18–20)

Example

W-2 from a payroll connection

1099 from uploaded documents

Form variant

Fields on every variant

Income boxes by variant

State boxes

Recipient and payer

Example

1040 from uploaded documents

Form 1040 fields

Attached schedules and forms

Example

Reading `fields`