Version: 2.0.0

Get

Use this endpoint to retrieve a W-2 submission and its records. Provide the SubmissionId to retrieve the whole submission, optionally narrowing to specific RecordIds.

GET formw2/get

Run in Postman

Request Params

Field	Type	Description
SubmissionId	GUID	An unique identifier generated by TaxBandits when a W-2 return is created. Mention the Form W-2 return's Submission ID that you want to get.
RecordId	GUID[]	An unique identifier generated by TaxBandits when a W-2 return is created. Mention the Form W-2 return's Record ID that you want to get.

Response Body

Field	Type	Description
FormW2Records	object[]	Contains information about Form W2 returns.
SubmissionManifest	object	SubmissionManifest provides brief information about a particular submission on the whole. It contains information like Submission ID Tax Year IsScheduleFiling & ScheduleFiling service details
TaxYear	String	Tax year of Form W-2 to be filed. Allowed values "2025", "2026"
IsFederal	Boolean	Federal Filing will be enabled when the value is True. Form W2 will be sent directly to the SSA.
IsState	Boolean	State Filing will be enabled when the value is True. Form W2 will be directly filed with the respective recipient states. Note: State Filing will not be created for the states that do not require State filing.
IsDistribution	Boolean	When TRUE, recipient distribution is enabled (postal mail / online access/email).
DistributionDetails	object[]	Distribution configuration. Required when IsDistribution is TRUE.
DistributionType	String	Recipient copy distribution type. Allowed values "POSTAL_ONLY", "ONLINE_ACCESS", "POSTAL_AND_ONLINE"
PostalType	String	Postal service type. Allowed values "USPS_FIRST_CLASS"
IsScheduleFiling	Boolean	When true, schedule filing services will be enabled for Form W-2 returns under this submission.
ScheduleFiling	object	Optional Contains the preferred date to submit the returns to the SSA. Required only when "IsScheduleFiling" is True.
EfileDate	String	Date of Schedule Filing. Enter the date in the format: MM/DD/YYYY or MM-DD-YYYY. Example: 01/25/2026 or 01-25-2026
ReturnHeader	object	Contains information about the Business details.
Business	object	Object to identify the Business Details.
BusinessId	GUID	Optional Use the unique Business ID (Generated by TaxBandits) that you received in the response of the Business CREATE Endpoint. If you do not have a Business ID, ignore the field. By giving the Business ID, you do not have to provide all the business information again.
PayerRef	String	Optional Your unique identifier for the payer. Can replace BusinessId in future requests. Size Range: 50
IsDefaultBusiness	Boolean	When set to TRUE, this business will be set as the default across requests that do not specify a business.
TINDetails	object	TIN information for the business.
Format	String	Specifies how the TIN is passed. Allowed values "PLAIN_TIN" — Pass TIN directly. "TOKENIZED_TIN" - Pass tokenized TIN.
TINType	String	Specify the TIN type of the business. Allowed values "EIN"
TIN	String	The TIN value according to the Format selected.
IndividualNm	object	Required when TINType is SSN. Provide individual name fields instead of BusinessNm.
FirstNm	String	The first name of the individual. Size Range: 20
MiddleNm	String	Optional Middle name of the individual. Size Range: 20
LastNm	String	The last name of the individual. Size Range: 20
Suffix	String	Optional Suffix of the individual's name. Allowed values "Jr", "Sr", "I", "II", "III", "IV", "V", "VI", "VII"
BusinessNm	String	Legal name of the business. Required when TINType is EIN. Size Range: 75
NameCtrl	String	Name control of the business as registered with the SSA. Size Range: 3..4
DBADetails	object[]	Optional DBA (Doing Business As) information.
DBANm	String	Name of the DBA. Size Range: 75
DBARef	String	Unique identifier for the DBA. Size Range: 1-50
DBAId	GUID	TaxBandits-generated DBA identifier.
Address	object[]	Address information of the DBA.
Address1	String	Street address or PO Box. Size Range: 46
Address2	String	Optional Suite or apartment number. Size Range: 46
City	String	DBA's city. Size Range: 50
ProvinceOrState	String	DBA's province or state name. Allowed values When the country code is US: Allowed values "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY", "AS", "FM", "GU", "MH", "MP", "PW", "PR", "VI", "AA", "AE", "AP" When the country code is CA: Allowed values "AB", "BC", "MB", "NB", "NL", "NT", "NS", "NU", "ON", "PE", "QC", "SK", "YT" Note: The size range is set to 50 for all countries except the United States and Canada.
Zipcd	String	DBA's ZIP code. Size Range: 5-16
Country	String	DBA's 2-character country code. Allowed values "US","AF", "AX", "AL", "AG", "AQ", "AN", "AO", "AV", "AY", "AC", "AR", "AM", "AA", "AT", "AS", "AU", "AJ", "BF", "BA", "FQ", "BG", "BB", "BO", "BE", "BH", "BN", "BD", "BT", "BL", "BK", "BC", "BV", "BR", "IO", "VI", "BX", "BU", "UV", "BM", "BY", "CB", "CM", "CA", "CV", "CJ", "CT", "CD", "CI", "CH", "KT", "IP", "CK", "CO", "CN", "CF", "CG", "CW", "CR", "CS", "IV", "HR", "CU", "UC", "CY", "EZ", "DA", "DX", "DJ", "DO", "DR", "TT", "EC", "EG", "ES", "EK", "ER", "EN", "ET", "FK", "FO", "FM", "FJ", "FI", "FR", "FP", "FS", "GB", "GA", "GG", "GM", "GH", "GI", "GR", "GL", "GJ", "GQ", "GT", "GK", "GV", "PU", "GY", "HA", "HM", "VT", "HO", "HK", "HQ", "HU", "IC", "IN", "ID", "IR", "IZ", "EI", "IS", "IT", "JM", "JN", "JA", "DQ", "JE", "JQ", "JO", "KZ", "KE", "KQ", "KR", "KN", "KS", "KV", "KU", "KG", "LA", "LG", "LE", "LT", "LI", "LY", "LS", "LH", "LU", "MC", "MK", "MA", "MI", "MY", "MV", "ML", "MT", "IM", "RM", "MR", "MP", "MX", "MQ", "MD", "MN", "MG", "MJ", "MH", "MO", "MZ", "WA", "NR", "BQ", "NP", "NL", "NC", "NZ", "NU", "NG", "NI", "NE", "NF", "CQ", "NO", "MU", "OC", "PK", "PS", "LQ", "PM", "PP", "PF", "PA", "PE", "RP", "PC", "PL", "PO", "RQ", "QA", "RO", "RS", "RW", "TB", "RN", "WS", "SM", "TP", "SA", "SG", "RI", "SE", "SL", "SN", "NN", "LO", "SI", "BP", "SO", "SF", "SX", "OD", "SP", "PG", "CE", "SH", "SC", "ST", "SB", "VC", "SU", "NS", "SV", "WZ", "SW", "SZ", "SY", "TW", "TI", "TZ", "TH", "TO", "TL", "TN", "TD", "TS", "TU", "TX", "TK", "TV", "UG", "UP", "AE", "UK", "UY", "UZ", "NH", "VE", "VM", "VQ", "WQ", "WF", "WI", "YM", "ZA", "ZI"
Email	String	Optional Email address of the Business. Size Range: ..100
Address	object	Primary address of the business.
Address1	String	Street address or PO Box of the business. Size Range: 46
Address2	String	Optional Suite or apartment number of the business. Size Range: 46
City	String	City of the business. Size Range: 50
ProvinceOrState	String	Province or state name of the business. Allowed values When the country code is US: Allowed values "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY", "AS", "FM", "GU", "MH", "MP", "PW", "PR", "VI", "AA", "AE", "AP" When the country code is CA: Allowed values "AB", "BC", "MB", "NB", "NL", "NT", "NS", "NU", "ON", "PE", "QC", "SK", "YT" Note: The size range is set to 50 for all countries except the United States and Canada.
ZipCd	String	ZIP code of the business. Size Range: 5-16
Country	String	2-character country code of the business. Allowed values "US","AF", "AX", "AL", "AG", "AQ", "AN", "AO", "AV", "AY", "AC", "AR", "AM", "AA", "AT", "AS", "AU", "AJ", "BF", "BA", "FQ", "BG", "BB", "BO", "BE", "BH", "BN", "BD", "BT", "BL", "BK", "BC", "BV", "BR", "IO", "VI", "BX", "BU", "UV", "BM", "BY", "CB", "CM", "CA", "CV", "CJ", "CT", "CD", "CI", "CH", "KT", "IP", "CK", "CO", "CN", "CF", "CG", "CW", "CR", "CS", "IV", "HR", "CU", "UC", "CY", "EZ", "DA", "DX", "DJ", "DO", "DR", "TT", "EC", "EG", "ES", "EK", "ER", "EN", "ET", "FK", "FO", "FM", "FJ", "FI", "FR", "FP", "FS", "GB", "GA", "GG", "GM", "GH", "GI", "GR", "GL", "GJ", "GQ", "GT", "GK", "GV", "PU", "GY", "HA", "HM", "VT", "HO", "HK", "HQ", "HU", "IC", "IN", "ID", "IR", "IZ", "EI", "IS", "IT", "JM", "JN", "JA", "DQ", "JE", "JQ", "JO", "KZ", "KE", "KQ", "KR", "KN", "KS", "KV", "KU", "KG", "LA", "LG", "LE", "LT", "LI", "LY", "LS", "LH", "LU", "MC", "MK", "MA", "MI", "MY", "MV", "ML", "MT", "IM", "RM", "MR", "MP", "MX", "MQ", "MD", "MN", "MG", "MJ", "MH", "MO", "MZ", "WA", "NR", "BQ", "NP", "NL", "NC", "NZ", "NU", "NG", "NI", "NE", "NF", "CQ", "NO", "MU", "OC", "PK", "PS", "LQ", "PM", "PP", "PF", "PA", "PE", "RP", "PC", "PL", "PO", "RQ", "QA", "RO", "RS", "RW", "TB", "RN", "WS", "SM", "TP", "SA", "SG", "RI", "SE", "SL", "SN", "NN", "LO", "SI", "BP", "SO", "SF", "SX", "OD", "SP", "PG", "CE", "SH", "SC", "ST", "SB", "VC", "SU", "NS", "SV", "WZ", "SW", "SZ", "SY", "TW", "TI", "TZ", "TH", "TO", "TL", "TN", "TD", "TS", "TU", "TX", "TK", "TV", "UG", "UP", "AE", "UK", "UY", "UZ", "NH", "VE", "VM", "VQ", "WQ", "WF", "WI", "YM", "ZA", "ZI"
ContactDetails	object[]	Details of the person the SSA can contact regarding the given business.
FirstNm	String	First name of the contact person. Size Range: 20
MiddleNm	String	Optional Middle name of the contact person. Size Range: 20
LastNm	String	Last name of the contact person. Size Range: 20
Suffix	String	Optional The suffix of the contact person. Allowed values "Jr", "Sr", "I", "II", "III", "IV", "V", "VI", "VII"
Phone	String	Optional Phone number of the contact person. Size Range: 10 digits
PhoneExtn	String	Optional Phone extension number. Size Range: 5
Email	String	Optional Email address of the contact person. Size Range: ..100
Fax	String	Optional Fax number of the contact person. Size Range: 10 digits
W2Specific	Object	Information specific to W-2 filings. Optional for 1099 and 94X.
KindOfEmployer	String	Identifies the kind of employer. Allowed values "FEDERALGOVT", "STATEORLOCAL501C", "NONGOVT501C", "STATEORLOCALNON501C", "NONEAPPLY"
KindOfPayer	String	Identifies the kind of Payer. Allowed values "REGULAR941", "REGULAR944", "AGRICULTURAL943", "HOUSEHOLD", "MILITARY", "MEDICAREQUALGOVEM", "RAILROADFORMCT1"
ReturnData	object[]	Contains information about the recipient details and Form W-2 details.
SequenceId	String	A unique reference ID for the submission that can be used to identify a particular record. The Sequence ID will be returned in the Response for your reference. Size Range: 50
ReturnManifest	object	Filing options for this record.
IsFederal	Boolean	Federal Filing for the return will be enabled when the value is True. Form W-2 will be sent directly to the SSA.
IsState	Boolean	State Filing for the return will be enabled when the value is True. Form W-2 will be directly filed with the respective recipient states. Note: State Filing will not be created for the states that do not require State filing.
IsDistribution	Boolean	When TRUE, recipient distribution is enabled (postal mail / online access/email).
DistributionDetails	object[]	Distribution configuration. Required when IsDistribution is TRUE.
DistributionType	String	Recipient copy distribution type. Allowed values "POSTAL_ONLY", "ONLINE_ACCESS", "POSTAL_AND_ONLINE"
PostalType	String	Postal service type. Allowed values "USPS_FIRST_CLASS"
Employee	object	Information about the Employee (Employee of the W-2).Required: Yes
EmployeeId	GUID	Unique EmployeeId generated by TaxBandits when the Employee was first created. If supplied, takes precedence over other identifiers.Required: Optional Size Range: 36
PayeeRef	String	Optional Your unique identifier for the employee. Can replace EmployeeId in future requests. Size Range: 50
TINDetails	object	Recipient TIN information.
Format	String	Specifies how the TIN is passed. Allowed values "PLAIN_TIN" — Pass TIN directly. "TOKENIZED_TIN" - Pass tokenized TIN.
TINType	String	Specify the TIN type of the recipient. Allowed values "SSN"
TIN	String	The TIN value, formatted according to the Format field selected.
IndividualNm	object	Required when TINType is SSN, ITIN, or ATIN. Provide individual name fields instead of BusinessNm.
FirstNm	String	The first name of the individual. Size Range: 20
MiddleNm	String	Optional The middle name of the individual. Size Range: 20
LastNm	String	The last name of the individual. Size Range: 20
Suffix	String	Optional The suffix of the individual's name. Allowed values "Jr", "Sr", "I", "II", "III", "IV", "V", "VI", "VII"
BusinessNm	String	Legal name of the recipient business. Required when TINType is EIN. Size Range: 75
NameCtrl	String	Name control of the business as registered with the SSA. Size Range: 3..4
DBADetails	object	Optional DBA (Doing Business As) information.
DBAId	GUID	TaxBandits-generated DBA identifier. Returned in the response.
DBANm	String	Name of the DBA. Size Range: 75
DBARef	String	Your unique identifier for this DBA. Size Range: 1–50
Address	object	Address information of the DBA.
Address1	String	Street address or PO Box. Size Range: 46
Address2	String	Optional Suite or apartment number. Size Range: 46
City	String	DBA's city. Size Range: 50
ProvinceOrState	String	DBA's province or state name. Allowed values When the country code is US: Allowed values "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY", "AS", "FM", "GU", "MH", "MP", "PW", "PR", "VI", "AA", "AE", "AP" When the country code is CA: Allowed values "AB", "BC", "MB", "NB", "NL", "NT", "NS", "NU", "ON", "PE", "QC", "SK", "YT" Note: The size range is set to 50 for all countries except the United States and Canada.
ZipCd	String	DBA's ZIP code. Size Range: 5–16
Country	String	DBA's 2-character country code. Allowed values "US","AF", "AX", "AL", "AG", "AQ", "AN", "AO", "AV", "AY", "AC", "AR", "AM", "AA", "AT", "AS", "AU", "AJ", "BF", "BA", "FQ", "BG", "BB", "BO", "BE", "BH", "BN", "BD", "BT", "BL", "BK", "BC", "BV", "BR", "IO", "VI", "BX", "BU", "UV", "BM", "BY", "CB", "CM", "CA", "CV", "CJ", "CT", "CD", "CI", "CH", "KT", "IP", "CK", "CO", "CN", "CF", "CG", "CW", "CR", "CS", "IV", "HR", "CU", "UC", "CY", "EZ", "DA", "DX", "DJ", "DO", "DR", "TT", "EC", "EG", "ES", "EK", "ER", "EN", "ET", "FK", "FO", "FM", "FJ", "FI", "FR", "FP", "FS", "GB", "GA", "GG", "GM", "GH", "GI", "GR", "GL", "GJ", "GQ", "GT", "GK", "GV", "PU", "GY", "HA", "HM", "VT", "HO", "HK", "HQ", "HU", "IC", "IN", "ID", "IR", "IZ", "EI", "IS", "IT", "JM", "JN", "JA", "DQ", "JE", "JQ", "JO", "KZ", "KE", "KQ", "KR", "KN", "KS", "KV", "KU", "KG", "LA", "LG", "LE", "LT", "LI", "LY", "LS", "LH", "LU", "MC", "MK", "MA", "MI", "MY", "MV", "ML", "MT", "IM", "RM", "MR", "MP", "MX", "MQ", "MD", "MN", "MG", "MJ", "MH", "MO", "MZ", "WA", "NR", "BQ", "NP", "NL", "NC", "NZ", "NU", "NG", "NI", "NE", "NF", "CQ", "NO", "MU", "OC", "PK", "PS", "LQ", "PM", "PP", "PF", "PA", "PE", "RP", "PC", "PL", "PO", "RQ", "QA", "RO", "RS", "RW", "TB", "RN", "WS", "SM", "TP", "SA", "SG", "RI", "SE", "SL", "SN", "NN", "LO", "SI", "BP", "SO", "SF", "SX", "OD", "SP", "PG", "CE", "SH", "SC", "ST", "SB", "VC", "SU", "NS", "SV", "WZ", "SW", "SZ", "SY", "TW", "TI", "TZ", "TH", "TO", "TL", "TN", "TD", "TS", "TU", "TX", "TK", "TV", "UG", "UP", "AE", "UK", "UY", "UZ", "NH", "VE", "VM", "VQ", "WQ", "WF", "WI", "YM", "ZA", "ZI"
DOB	String	Optional Date of Birth of the recipient. Format: MM/DD/YYYY
Address	object	Primary address of the recipient.
Address1	String	Street address or PO Box of the recipient. Size Range: 46
Address2	String	Optional Suite or apartment number of the recipient. Size Range: 46
City	String	City of the recipient. Size Range: 50
ProvinceOrState	String	Province or state name of the recipient. Allowed values When the country code is US: Allowed values "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY", "AS", "FM", "GU", "MH", "MP", "PW", "PR", "VI", "AA", "AE", "AP" When the country code is CA: Allowed values "AB", "BC", "MB", "NB", "NL", "NT", "NS", "NU", "ON", "PE", "QC", "SK", "YT" Note: The size range is set to 50 for all countries except the United States and Canada.
ZipCd	String	ZIP code of the recipient. Size Range: 5 – 16
Country	String	2-character country code of the recipient. Allowed values "US","AF", "AX", "AL", "AG", "AQ", "AN", "AO", "AV", "AY", "AC", "AR", "AM", "AA", "AT", "AS", "AU", "AJ", "BF", "BA", "FQ", "BG", "BB", "BO", "BE", "BH", "BN", "BD", "BT", "BL", "BK", "BC", "BV", "BR", "IO", "VI", "BX", "BU", "UV", "BM", "BY", "CB", "CM", "CA", "CV", "CJ", "CT", "CD", "CI", "CH", "KT", "IP", "CK", "CO", "CN", "CF", "CG", "CW", "CR", "CS", "IV", "HR", "CU", "UC", "CY", "EZ", "DA", "DX", "DJ", "DO", "DR", "TT", "EC", "EG", "ES", "EK", "ER", "EN", "ET", "FK", "FO", "FM", "FJ", "FI", "FR", "FP", "FS", "GB", "GA", "GG", "GM", "GH", "GI", "GR", "GL", "GJ", "GQ", "GT", "GK", "GV", "PU", "GY", "HA", "HM", "VT", "HO", "HK", "HQ", "HU", "IC", "IN", "ID", "IR", "IZ", "EI", "IS", "IT", "JM", "JN", "JA", "DQ", "JE", "JQ", "JO", "KZ", "KE", "KQ", "KR", "KN", "KS", "KV", "KU", "KG", "LA", "LG", "LE", "LT", "LI", "LY", "LS", "LH", "LU", "MC", "MK", "MA", "MI", "MY", "MV", "ML", "MT", "IM", "RM", "MR", "MP", "MX", "MQ", "MD", "MN", "MG", "MJ", "MH", "MO", "MZ", "WA", "NR", "BQ", "NP", "NL", "NC", "NZ", "NU", "NG", "NI", "NE", "NF", "CQ", "NO", "MU", "OC", "PK", "PS", "LQ", "PM", "PP", "PF", "PA", "PE", "RP", "PC", "PL", "PO", "RQ", "QA", "RO", "RS", "RW", "TB", "RN", "WS", "SM", "TP", "SA", "SG", "RI", "SE", "SL", "SN", "NN", "LO", "SI", "BP", "SO", "SF", "SX", "OD", "SP", "PG", "CE", "SH", "SC", "ST", "SB", "VC", "SU", "NS", "SV", "WZ", "SW", "SZ", "SY", "TW", "TI", "TZ", "TH", "TO", "TL", "TN", "TD", "TS", "TU", "TX", "TK", "TV", "UG", "UP", "AE", "UK", "UY", "UZ", "NH", "VE", "VM", "VQ", "WQ", "WF", "WI", "YM", "ZA", "ZI"
Email	String	Email address of the recipient. Size Range: 100 Note: Required if DistributionType is ONLINE_ACCESS.
Fax	String	Optional Fax number of the recipient. Size Range: 10
Phone	String	Optional Phone number of the recipient. Size Range: 10
W2FormData	object	Form W-2 line-item data for this Employee. Required: Yes
Wages	Number	Box 1 — Wages, Tips, Other Compensation. Required: Yes Size Range: 0 – 999999999.99 Format: Decimal (up to 2 dp)
FedTaxWH	Number	Optional Box 2 — Federal Income Tax Withheld. Size Range: 0 – 999999999.99
SocSecWages	Number	Optional Box 3 — Social Security Wages. Size Range: 0 – 999999999.99
SocSecTaxWH	Number	Optional Box 4 — Social Security Tax Withheld. Size Range: 0 – 999999999.99
MediWages	Number	Optional Box 5 — Medicare Wages and Tips. Size Range: 0 – 999999999.99
MediTaxWH	Number	Optional Box 6 — Medicare Tax Withheld. Size Range: 0 – 999999999.99
SocSecTips	Number	Optional Box 7 — Social Security Tips. Size Range: 0 – 999999999.99
AllocatedTips	Number	Optional Box 8 — Allocated Tips. Size Range: 0 – 999999999.99
DependtCareBenefits	Number	Optional Box 10 — Dependent Care Benefits. Size Range: 0 – 999999999.99
Sec457Plan	Number	Optional Box 11 — Nonqualified Plans, Section 457 portion. Size Range: 0 – 999999999.99
NonSec457Plan	Number	Optional Box 11 — Nonqualified Plans, Non-Section 457 portion. Size Range: 0 – 999999999.99
CompCode1	String	Optional Box 12 — Code #1 (e.g., A, B, C, D, DD, TT, TP, TA, …). Size Range: 1–2 Note: Codes TT, TP and TA were introduced for TY 2026 to support OBBBA tip / overtime reporting.
CompAmt1	Number	Box 12 — Amount for Code #1. Required: Conditional Size Range: 0 – 999999999.99
CompCode2	String	Optional Box 12 — Code #2. Size Range: 1–2 Note: Codes TT, TP and TA were introduced for TY 2026 to support OBBBA tip / overtime reporting.
CompAmt2	Number	Box 12 — Amount for Code #2. Required: Conditional Size Range: 0 – 999999999.99
CompCode3	String	Optional Box 12 — Code #3. Size Range: 1–2 Note: Codes TT, TP and TA were introduced for TY 2026 to support OBBBA tip / overtime reporting.
CompAmt3	Number	Box 12 — Amount for Code #3. Required: Conditional Size Range: 0 – 999999999.99
CompCode4	String	Optional Box 12 — Code #4. Size Range: 1–2 Note: Codes TT, TP and TA were introduced for TY 2026 to support OBBBA tip / overtime reporting.
CompAmt4	Number	Box 12 — Amount for Code #4. Required: Conditional Size Range: 0 – 999999999.99
IsStatEmp	Boolean	Optional Box 13 — Statutory Employee indicator. Allowed values true, false
IsRetPlan	Boolean	Optional Box 13 — Retirement Plan indicator. Allowed values true, false
Is3rdPartySickPay	Boolean	Optional Box 13 — Third-Party Sick Pay indicator. Allowed values true, false
Other	String	Optional Box 14 — Other. Free-form text used to report items such as state PFL / PML, union dues, etc. Size Range: 1–100
TTOC1	String	Treasury Tipped Occupation Code #1 — identifies the Employee's qualifying tipped occupation. New for TY 2026 — supports OBBBA No-Tax-on-Tips reporting. Size Range: 1–3 Applicable only when TaxYear is 2026. Allowed values "000","101", "102", "103", "104", "105", "106", "107", "108","109","110","201","202", "203", "204", "205","206","207", "208", "209","210", "211", "301", "302", "303", "304", "401", "402", "403", "404", "405", "406", "407", "408", "409", "501", "502", "503", "504", "505", "506", "507", "508", "509", "510", "601", "602", "603","604", "605", "606", "607", "608", "609", "610", "611", "701", "702", "703", "704", "705", "706", "801", "802", "803", "804", "805", "806", "807", "808", "809", "810"
TTOC2	String	Optional Treasury Tipped Occupation Code #2 — secondary qualifying tipped occupation, if applicable. New for TY 2026. (TY 2026 only) Size Range: 1–3 Applicable only when TaxYear is 2026. Allowed values "000","101", "102", "103", "104", "105", "106", "107", "108","109","110","201","202", "203", "204", "205","206","207", "208", "209","210", "211", "301", "302", "303", "304", "401", "402", "403", "404", "405", "406", "407", "408", "409", "501", "502", "503", "504", "505", "506", "507", "508", "509", "510", "601", "602", "603","604", "605", "606", "607", "608", "609", "610", "611", "701", "702", "703", "704", "705", "706", "801", "802", "803", "804", "805", "806", "807", "808", "809", "810"
ControlNum	String	Optional Box D — Control Number assigned by the Employer to uniquely identify the W-2. Size Range: 1–14
State	object []	State filing data — Boxes 15–20. Required: Conditional Note: Required when ReturnManifest.IsState is true.
StateCd	String	Box 15 — Two-letter State Code. Required: Yes (if State present) Size Range: 2
StateIdNum	String	Box 15 — Employer's State ID Number. Required: Conditional Size Range: 1–20
StateWages	Number	Box 16 — State Wages, Tips, etc. Required: Conditional Size Range: 0 – 999999999.99
StateTax	Number	Optional Box 17 — State Income Tax. Size Range: 0 – 999999999.99
LocalityData	object	Optional Boxes 18–20 — Local income / locality information.
LocalWages	Number	Box 18 — Local Wages, Tips, etc. Required: Conditional Size Range: 0 – 999999999.99
LocalTax	Number	Optional Box 19 — Local Income Tax. Size Range: 0 – 999999999.99
LocalityNm	String	Box 20 — Locality Name. Required: Conditional Size Range: 1–50
County	String	Optional County name (used in states where county-level reporting is required). Size Range: 1–50
TaxTypeCd	String	Optional Tax Type Code identifying the type of local tax being reported. Size Range: 1–2 Allowed values "C", "D", "E", "F", "H", "I", "K", "N"
SchoolDistrictNum	String	School District Number (required for certain Ohio / Pennsylvania filings). Required: Conditional Size Range: 1–10
EmployeeStateSpecificData	object	State-specific reporting fields keyed by state code. Only the states relevant to the Employee need to be supplied.
MD	object	Optional Maryland-specific W-2 fields.
W4ExemptionCount	Number	Maryland — number of exemptions claimed on Form MW-507. Size Range: 0 – 99
NJ	object	Optional New Jersey-specific W-2 fields.
PvtFmlLeaveInsuranceNum	String	Optional NJ — Private Family Leave Insurance Plan Number. Size Range: 1–20
FmlLeaveInsuranceWH	Number	Optional NJ — Family Leave Insurance Withheld. Size Range: 0 – 999999999.99
PvtDisabilityPlanNum	String	Optional NJ — Private Disability Plan Number. Size Range: 1–20
DisabilityInsuranceWH	Number	Optional NJ — Disability Insurance Withheld. Size Range: 0 – 999999999.99
CombNJUnempInsWrkFrceDevProgHCSubWH	Number	NJ — Combined withholding for Unemployment Insurance, Workforce Development Program and Health Care Subsidy. Size Range: 0 – 999999999.99
DeffCompAmt	Number	Optional NJ — Deferred Compensation amount. Size Range: 0 – 999999999.99
IsRetirementPlan	Boolean	Optional NJ — Indicates whether the Employee was an active participant in a retirement plan. Allowed values true, false
OR	object	Optional Oregon-specific W-2 fields.
DateFirstEmployed	String	Optional Oregon — Date the Employee was first employed. Format: MM/DD/YYYY
DateOfSeparation	String	Optional Oregon — Date of Separation, if applicable. Format: MM/DD/YYYY
TaxableWagesForStateTransitTax	Number	Optional Oregon — Taxable Wages for the Statewide Transit Tax (STT). Size Range: 0 – 999999999.99
StateTransitTaxWH	Number	Optional Oregon — State Transit Tax Withheld. Size Range: 0 – 999999999.99
ME	object	Optional Maine-specific W-2 fields.
MEPERScontribution	Number	Optional Maine — Maine Public Employees Retirement System (MEPERS) contribution. Size Range: 0 – 999999999.99

Request Params

Sample	Description	Action
Sample 1	Query Params - Use the SubmissionId alone to get the full submission, or include RecordId to get a specific record.

Sample 1

FormW2/get?submissionId=519a84f4-5e56-496a-82f3-18f51fdf3d75&recordIds=519a84f4-5e56-496a-82f3-18f51fdf3d75,519a84f4-5e56-496a-82f3-18f51fdf3d75

Response JSON

Response	Description	Action
200	Success Response - This is a sample response for successful API requests.

Response: 200

{
  "FormW2Records": [
    {
      "SubmissionManifest": {
        "SubmissionId": "e50c27b8-631c-45f0-be19-f786fc69ba60",
        "TaxYear": "2026",
        "IsFederal": true,
        "IsState": true,
        "IsDistribution": true,
        "DistributionDetails": {
          "DistributionType": "POSTAL_AND_ONLINE",
          "PostalType": "USPS_FIRST_CLASS"
        },
        "IsScheduleFiling": true,
        "ScheduleFiling": {
          "EfileDate": "01/25/2026"
        }
      },
      "ReturnHeader": {
        "Business": {
          "PayerRef": "Snow123",
          "BusinessId": null,
          "IsDefaultBusiness": true,
          "TINDetails": {
            "Format": "PLAIN_TIN",
            "TINType": "EIN",
            "TIN": "45-9875461"
          },
          "IndividualNm": {
            "FirstNm": "James",
            "MiddleNm": "A",
            "LastNm": "Anderson",
            "Suffix": "Jr"
          },
          "BusinessNm": "Snowdaze LLC",
          "NameCtrl": "SNOW",
          "DBADetails": {
            "DBANm": "Iceberg Icecreams",
            "DBARef": "DBA1001",
            "DBAId": null,
            "Address": {
              "Address1": "123 Main St",
              "Address2": "Suite 1001",
              "City": "Rock Hill",
              "ProvinceOrState": "SC",
              "ZipCd": "29730",
              "Country": "US"
            }
          },
          "Email": "james@sample.com",
          "Address": {
            "Address1": "123 Main St",
            "Address2": "Suite 1001",
            "City": "Rock Hill",
            "ProvinceOrState": "SC",
            "ZipCd": "29730",
            "Country": "US"
          },
          "ContactDetails": {
            "FirstNm": "James",
            "MiddleNm": "A",
            "LastNm": "Anderson",
            "Suffix": "Jr",
            "Phone": "8035551234",
            "PhoneExtn": "101",
            "Email": "contact@snowdaze.com",
            "Fax": "8035555678"
          }
        }
      },
      "ReturnData": [
        {
          "SequenceId": "1",
          "RecordId": "cfd6fe66-ac9f-49f7-b8a3-2d064abeeb9b",
          "IsFederal": true,
          "IsState": true,
          "IsDistribution": true,
          "DistributionDetails": {
            "DistributionType": "POSTAL_ONLY",
            "PostalType": "USPS_FIRST_CLASS"
          },
          "IsForced": false,
          "Recipient": {
            "PayeeRef": "DAI001",
            "TINDetails": {
              "Format": "PLAIN_TIN",
              "TINType": "EIN",
              "TIN": "45-9875461"
            },
            "IndividualNm": {
              "FirstNm": "James",
              "MiddleNm": "A",
              "LastNm": "Anderson",
              "Suffix": "Jr",
              "DOB": null
            },
            "BusinessNm": "Snowdaze LLC",
            "NameCtrl": "SNOW",
            "DBADetails": {
              "DBANm": "Iceberg Icecreams",
              "DBARef": "DBA1001",
              "Address": {
                "Address1": "123 Main St",
                "Address2": "Suite 1001",
                "City": "Rock Hill",
                "ProvinceOrState": "SC",
                "ZipCd": "29730",
                "Country": "US"
              }
            },
            "Address": {
              "Address1": "123 Main St",
              "Address2": "Suite 1001",
              "City": "Rock Hill",
              "ProvinceOrState": "SC",
              "ZipCd": "29730",
              "Country": "US"
            },
            "Email": "shawn@sample.com",
            "Fax": "6634567890",
            "Phone": "9634567890"
          },
          "W2FormData": {
            "Wages": 580450,
            "FedTaxWH": 36820,
            "SocSecWages": 18400,
            "SocSecTaxWH": 11439,
            "MediWages": 184501,
            "MediTaxWH": 0,
            "SocSecTips": 501,
            "AllocatedTips": 45.89,
            "DependtCareBenefits": 78,
            "Sec457Plan": 100,
            "NonSec457Plan": 0,
            "CompCode1": "TA",
            "CompAmt1": 100,
            "CompCode2": "TT",
            "CompAmt2": 100,
            "CompCode3": "TP",
            "CompAmt3": 100,
            "CompCode4": "A",
            "CompAmt4": 100,
            "IsStatEmp": true,
            "IsRetPlan": true,
            "Is3rdPartySickPay": true,
            "Other": "MA PFL 316.96, MA PML 493.10",
            "TTOC1": "407",
            "TTOC2": "409",
            "ControlNum": "35231",
            "States": {
              "StateCd": "CA",
              "StateIdNum": "999-9999-9",
              "StateWinnings": 1000.56,
              "StateWH": 100.28,
              "LocalWinnings": 300.23,
              "LocalWH": 100.45,
              "LocalityNm": "Pristine"
            }
          }
        }
      ],
      "StateReconData": null
    }
  ],
  "Errors": null
}

  package main

  import (
      "fmt"
      "io"
      "net/http"
  )

  func main() {
      url := "<APIURL>/v2.0.0/FormW2/get?submissionId=519a84f4-5e56-496a-82f3-18f51fdf3d75&recordIds=519a84f4-5e56-496a-82f3-18f51fdf3d75%2C519a84f4-5e56-496a-82f3-18f51fdf3d75"
      method := "GET"

      client := &http.Client{}

      req, err := http.NewRequest(method, url, nil)
      if err != nil {
          fmt.Println(err)
          return
      }

      req.Header.Add("Content-Type", "application/json")
      req.Header.Add("Authorization", "<ACCESS_TOKEN>")

      res, err := client.Do(req)
      if err != nil {
          fmt.Println(err)
          return
      }
      defer res.Body.Close()

      body, err := io.ReadAll(res.Body)
      if err != nil {
          fmt.Println(err)
          return
      }

      fmt.Println(string(body))
  }

  const axios = require('axios');
  let data = '';

  let config = {
  method: 'get',
  maxBodyLength: Infinity,
  url: '<APIURL>/v2.0.0/FormW2/get?submissionId=519a84f4-5e56-496a-82f3-18f51fdf3d75&recordIds=519a84f4-5e56-496a-82f3-18f51fdf3d75,519a84f4-5e56-496a-82f3-18f51fdf3d75',
  headers: { 
      'Content-Type': 'application/json', 
      'Authorization': '<ACCESS_TOKEN>'
  },
  data : data
  };

  axios.request(config)
  .then((response) => {
  console.log(JSON.stringify(response.data));
  })
  .catch((error) => {
  console.log(error);
  });

  import http.client
  import json

  conn = http.client.HTTPSConnection("<APIURL>")
  payload = ''
  headers = {
  'Content-Type': 'application/json',
  'Authorization': '<ACCESS_TOKEN>'
  }
  conn.request("GET", "/v2.0.0/FormW2/get?submissionId=519a84f4-5e56-496a-82f3-18f51fdf3d75&recordIds=519a84f4-5e56-496a-82f3-18f51fdf3d75,519a84f4-5e56-496a-82f3-18f51fdf3d75", payload, headers)
  res = conn.getresponse()
  data = res.read()
  print(data.decode("utf-8"))

  var client = new HttpClient();
  var request = new HttpRequestMessage(HttpMethod.Get, "<APIURL>/v2.0.0/FormW2/get?submissionId=519a84f4-5e56-496a-82f3-18f51fdf3d75&recordIds=519a84f4-5e56-496a-82f3-18f51fdf3d75,519a84f4-5e56-496a-82f3-18f51fdf3d75");
  request.Headers.Add("Authorization", "<ACCESS_TOKEN>");
  var content = new StringContent("", null, "application/json");
  request.Content = content;
  var response = await client.SendAsync(request);
  response.EnsureSuccessStatusCode();
  Console.WriteLine(await response.Content.ReadAsStringAsync());

  require "uri"
  require "json"
  require "net/http"

  url = URI("<APIURL>/v2.0.0/FormW2/get?submissionId=519a84f4-5e56-496a-82f3-18f51fdf3d75&recordIds=519a84f4-5e56-496a-82f3-18f51fdf3d75,519a84f4-5e56-496a-82f3-18f51fdf3d75")

  http = Net::HTTP.new(url.host, url.port);
  request = Net::HTTP::Get.new(url)
  request["Content-Type"] = "application/json"
  request["Authorization"] = "<ACCESS_TOKEN>"

  response = http.request(request)
  puts response.read_body

  OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
  MediaType mediaType = MediaType.parse("application/json");
  RequestBody body = RequestBody.create(mediaType, "");
  Request request = new Request.Builder()
  .url("<APIURL>/v2.0.0/FormW2/get?submissionId=519a84f4-5e56-496a-82f3-18f51fdf3d75&recordIds=519a84f4-5e56-496a-82f3-18f51fdf3d75,519a84f4-5e56-496a-82f3-18f51fdf3d75")
  .method("GET", body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Authorization", "<ACCESS_TOKEN>")
  .build();
  Response response = client.newCall(request).execute();

  curl --location '<APIURL>/v2.0.0/FormW2/get?submissionId=519a84f4-5e56-496a-82f3-18f51fdf3d75&recordIds=519a84f4-5e56-496a-82f3-18f51fdf3d75%2C519a84f4-5e56-496a-82f3-18f51fdf3d75'   --header 'Content-Type: application/json'   --header 'Authorization: <ACCESS_TOKEN>'   --data ''

W-9/W-8 Automation

1099 Automation

TIN Matching

W-2 Automation

941/940 Automation

1098-T Automation

ACA Automation

Extension Automation

1042-S Automation

Supported Forms

Gig Software

Payroll Software

Affiliate Software

HOA Software

Reselling Platform

HCM Providers

Property Management

Healthcare Market Research Platforms

Get

Get

Request Params

Response Body

Sample 1

Response: 200