Tax document
The Tax Document entity in Treasury.
A tax document is the IRS-reportable record we hold for each US
Recipient you've paid in a given tax year — typically a 1099-NEC
for contractors or 1099-MISC for other payments. The document is built from two
inputs you supply: the recipient's W-9 (collected via
POST /treasury/recipients/{id}/request-w9) and the cumulative payout total
for the year. Easy tracks both and produces the form when the year closes.
Lifecycle
not_requested— Default state for a new recipient. No W-9 has been asked for and the recipient is below the IRS threshold.requested—POST /treasury/recipients/{id}/request-w9has emailed the recipient. They have 72 hours to submit before the link expires.received— Recipient submitted the form. Tax ID is tokenized at intake and stored only as a token +tax_id_type(ssn|ein|itin).verified— Tax ID matches IRS TIN-matching service (where enabled for your account). The recipient is fully eligible for year-end issuance.expired— Form aged out (W-9 is good for the life of the recipient unless their info changes; this state is reserved for partial submissions that never completed).
The form itself is generated from the totals in
GET /treasury/recipients/tax-report once the calendar year closes.
Relationships
Exactly one tax document per Recipient per tax year (for recipients meeting the threshold). Built from the cumulative net of all completed Payouts to that recipient in the year, sourced from Settlement records.
Fields that matter
tax_id_type("ssn" | "ein" | "itin" | "none") — discriminator for which form applies.tax_id(string, 4–11 chars) — raw value sent on intake; never stored raw. Subsequent reads return only the type and a token.w9_status— see lifecycle states above.w9_received_at,w9_expires_at(stringISO-8601) — audit timestamps.