# FormW2

# Create

The Request Payload has manifest data (describes the Tax Form Type, Tax Year, etc.), business information, and data required to create the tax return. The CREATE endpoint takes in the Request Payload, validates data, applies the business rules, and creates the appropriate tax return. A unique Id called “Submission ID” is created and passed back to the sender when a tax return is created. A “Submission” is used to refer to the transaction between the client and the API server. The API will create a Unique ID for the business data if the EIN (Employer Identification Number) is not in the database. Any subsequent API calls can use the Business ID instead of sending the complete business data every time. Another Unique ID called “Record Id” is created to identify the records inside the submission.When the “Form W2 Create” endpoint is called, that many number of Record Ids are created for each employee record inside the single submission. Of course, one Submission Id is created for the entire transaction.

POST FormW2/Create

Request Body

Field	Type	Description
SubmissionManifest	object	SubmissionManifest provides the brief information about a particular submission on the whole. It contains information like Submission ID, Tax Year, IsPostal, IsFederalFiling, IsStateFiling, IsOnlineAccess, IsScheduleFiling & ScheduleFiling service details.
SubmissionId	Guid	Unique identifier created by TaxBandits for each submission. Not required when you are creating a return.
TaxYear	string	Tax year of Form W2 to be filed. Allowed values: "2021"
IsFederalFiling	Boolean	Federal Filing for the return will be enabled when the value is True. Form W2 will be sent directly to the IRS.
IsStateFiling	Boolean	State Filing for the return will be enabled when the value is True. Form W2 will be directly filed with the respective employee states. Note: State Filing will not be created for the states that do not require State filing.
IsPostal	Boolean	Postal Order will be created when the value is set as True. Once the return is Transmitted, Form W2 employee copies will be postal mailed to the employee's address via USPS. Note: Postal Orders for Foreign Address will not be created.
IsOnlineAccess	Boolean	Online Access will be enabled when the value is set as True. Once the return is Transmitted, an email with the link to the secure TaxBandits portal will be sent to the employee. The employee can provide consent and download Form W2 employee copies from the portal.
IsScheduleFiling	Boolean	When true, schedule filing services will be provided for W2 returns under this submission.
ScheduleFiling	object	Contains preferred date to submit the returns to the IRS. 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: 10/20/2021 or 10-20-2021
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), you received in the response of the Business CREATE Endpoint. If you have 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` An unique identifier for each payer completing their information. This identifier can be used in future references of the payer in the API. Size Range: ..50
BusinessNm	string	Name of the business Size Range: ..75
TradeNm	string	`Optional` Name under which the business operates Size Range: ..75
IsEIN	Boolean	When true, identifies the business with an EIN.
EINorSSN	string	Enter the Employer Identification Number (EIN) as you are filing Form W-2. You can not file Form W-2 with your SSN. Size Range: 9
Email	string	Email address of the Business Size Range: ..40
ContactNm	string	Name of the person who can be contacted by the IRS Size Range: ..27
Phone	string	Phone number of the business Size Range: 10
PhoneExtn	string	`Optional` Extension of the business phone number Size Range: ..5
Fax	string	`Optional` Fax number of the Business Size Range: 10
BusinessType	string	`Optional` Type of business. Optional for W-2/1099 and mandatory for 94X series Size Range: 4 Allowed values: "ESTE", "PART", "CORP", "EORG", "SPRO"
SigningAuthority	object	`Optional` Details of the person who is authorized to sign the return
Name	string	`Optional` Name of the signing authority Size Range: ..35
Phone	string	`Optional` Phone number of the signing authority Size Range: 10
BusinessMemberType	string	`Optional` Business title of the signing authority Size Range: 5..29 Allowed values: "CORPORATESECRETARY", "SECRETARYTREASURER", "PARTNER", "GENERALPARTNER", "LIMITEDPARTNER", "LLCMEMBER", "MANAGINGMEMBER", "MANAGER", "TAXMATTERPARTNER", "PRESIDENT", "VICEPRESIDENT", "CORPORATETREASURER", "TREASURER", "ASSISTANTTREASURER", "CHIEFACCOUNTINGOFFICER", "CHIEFEXECUTIVEOFFICER", "CHIEFFINANCIALOFFICER", "TAXOFFICER", "CHIEFOPERATINGOFFICER", "CORPORATEOFFICER", "EXECUTIVEDIRECTOR", "DIRECTOR", "CHAIRMAN", "EXECUTIVEADMINISTRATOR", "RECEIVER", "PASTOR", "ASSISTANTTORELIGIOUSLEADER", "REVEREND", "PRIEST", "MINISTER", "RABBI", "LEADEROFRELIGIOUSORGANIZATION", "SECRETARY", "DIRECTOROFTAXATION", "DIRECTOROFPERSONNEL", "ADMINISTRATOR", "EXECUTOR", "TRUSTEE", "FIDUCIARY", "OWNER", "SOLEPROPRIETOR", "MEMBER", "SOLEMEMBER"
KindOfEmployer	string	Identifies the kind of employer. Mandatory for W-2 and optional for 1099-MISC and 94X series Allowed values: "FEDERALGOVT", "STATEORLOCAL501C", "NONGOVT501C", "STATEORLOCALNON501C", "NONEAPPLY"
KindOfPayer	string	Identifies the kind of payer. This field is mandatory in W-2 and optional in 1099-MISC and 94X series Allowed values: "REGULAR941", "REGULAR944", "AGRICULTURAL943", "HOUSEHOLD", "MILITARY", "MEDICAREQUALGOVEM", "RAILROADFORMCT1"
IsBusinessTerminated	Boolean	When true, identifies the business as terminated.
IsForeign	Boolean	When true, identifies the business address with a foreign address.
USAddress	object	If IsForeign is false, pass US address of the business
Address1	string	Employer/Payer's US address (street address or post office box of that locality) Size Range: ..35
Address2	string	`Optional` Employer/Payer's suite or apartment Size Range: ..35
City	string	Employer/Payer's city Size Range: ..27
State	string	Employer/Payer's state code. Refer Static values. Size Range: 2 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"
ZipCd	string	Employer/Payer's zip code
ForeignAddress	object	If IsForeign is true, pass foreign address of the business
Address1	string	Employer/Payer's foreign address (street address or post office box of that locality) Size Range: ..35
Address2	string	`Optional` Employer/Payer's suite or apartment Size Range: ..35
City	string	Employer/Payer's city Size Range: ..27
ProvinceOrStateNm	string	Employer/Payer's province or state name Size Range: ..30
Country	string	Employer/Payer's country Size Range: 2 Allowed values: "US", "CA", "MX", "AF", "AX", "XI", "AL", "AG", "AQ", "AN", "AO", "AV", "AY", "AC", "AR", "AM", "AA", "XA", "AT", "AS", "AU", "AJ", "XZ", "BF", "BA", "FQ", "BG", "BB", "BS", "BO", "BE", "BH", "BN", "BD", "BT", "BL", "BK", "BC", "BV", "BR", "IO", "VI", "BX", "BU", "UV", "BM", "BY", "CB", "CM", "XY", "CV", "CJ", "CT", "CD", "XC", "CI", "CH", "KT", "IP", "CK", "CO", "CN", "CF", "CG", "CW", "CR", "VP", "CS", "IV", "HR", "CU", "CY", "EZ", "DA", "DX", "DJ", "DO", "DR", "TT", "EC", "EG", "ES", "UK", "EK", "ER", "EN", "ET", "EU", "FK", "FO", "FM", "FJ", "FI", "FR", "FG", "FP", "FS", "GB", "GA", "GZ", "GG", "GM", "GH", "GI", "GO", "GR", "GL", "GJ", "GP", "GQ", "GT", "GK", "GV", "PU", "GY", "HA", "HM", "HO", "HK", "HQ", "HU", "IC", "IN", "ID", "IR", "IZ", "EI", "IS", "IT", "JM", "JN", "JA", "DQ", "JE", "JQ", "JO", "JU", "KZ", "KE", "KQ", "KR", "KN", "KS", "KU", "KG", "LA", "LG", "LE", "LT", "LI", "LY", "LS", "LH", "LU", "MC", "MK", "MA", "MI", "MY", "MV", "ML", "MT", "IM", "RM", "MB", "MR", "MP", "MF", "MQ", "MD", "MN", "MG", "MJ", "MH", "MO", "MZ", "XM", "WA", "NR", "BQ", "NP", "NL", "NT", "NC", "NZ", "NU", "NG", "NI", "NE", "NF", "XN", "CQ", "NO", "MU", "OC", "PK", "LQ", "PS", "PM", "PP", "PF", "PA", "PE", "RP", "PC", "PL", "PO", "RQ", "QA", "RE", "RO", "RS", "RW", "WS", "SM", "TP", "SA", "XS", "SG", "RI", "SE", "SL", "SN", "XR", "LO", "SI", "BP", "SO", "SF", "SX", "SP", "PG", "CE", "SH", "SC", "ST", "SB", "VC", "SU", "NS", "SV", "WZ", "SW", "SZ", "SY", "TW", "TI", "TZ", "TH", "TO", "TL", "TN", "TD", "XT", "TE", "TS", "TU", "TX", "TK", "TV", "UG", "UP", "AE", "UY", "UZ", "NH", "VT", "VE", "VM", "VQ", "WQ", "XW", "WF", "WE", "WI", "YM", "YI", "ZA", "ZI"
PostalCd	string	Employer/Payer's postal code
ReturnData	object[]	Contains information about the employee details and Form W2 details.
SequenceId	string	An 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
RecordId	Guid	Unique identifier of a record. Not required when you are creating a return.
Employee	object	Object to identify the employee details.
EmployeeId	Guid	An unique ID generated by TaxBandits after the return is created and will be returned in the Response. You can use this id for your future reference to Update.
SSN	string	Employee's Social Security Number (SSN) Size Range: 9
FirstNm	string	Employee's first name.
MiddleNm	string	`Optional` Employee's middle name.
LastNm	string	Employee's last name.
Suffix	string	`Optional` Employee's suffix. Allowed values: "Jr", "Sr", "I", "II", "III", "IV", "V", "VI", "VII"
Email	string	`Optional` Employee's email address. Size Range: 0..40
Fax	string	`Optional` Employee's fax number. Size Range: 10
Phone	string	`Optional` Employee's phone number Size Range: 10
IsForeign	Boolean	When true, identifies the employee address with a foreign address.
USAddress	object	Object to identify the employee's US address
Address1	string	Employee's US address (street address or post office box of that locality) Size Range: ..35
Address2	string	Employee's suite or apartment Size Range: ..35
City	string	Employee's city Size Range: ..27
State	string	Employee's State code. Refer Static values. Size Range: 2 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"
ZipCd	string	Employee's zip code
ForeignAddress	object	If IsForeign is true, pass foreign address of the employee
Address1	string	Employee's foreign address (street address or post office box of that locality) Size Range: ..35
Address2	string	`Optional` Employee's suite or apartment Size Range: ..35
City	string	Employee's city. Size Range: ..27
ProvinceOrStateNm	string	Employee's Province or State Name. Size Range: ..30
Country	string	Employee's country code. Refer Static values. Size Range: 2 Allowed values: "US", "CA", "MX", "AF", "AX", "XI", "AL", "AG", "AQ", "AN", "AO", "AV", "AY", "AC", "AR", "AM", "AA", "XA", "AT", "AS", "AU", "AJ", "XZ", "BF", "BA", "FQ", "BG", "BB", "BS", "BO", "BE", "BH", "BN", "BD", "BT", "BL", "BK", "BC", "BV", "BR", "IO", "VI", "BX", "BU", "UV", "BM", "BY", "CB", "CM", "XY", "CV", "CJ", "CT", "CD", "XC", "CI", "CH", "KT", "IP", "CK", "CO", "CN", "CF", "CG", "CW", "CR", "VP", "CS", "IV", "HR", "CU", "CY", "EZ", "DA", "DX", "DJ", "DO", "DR", "TT", "EC", "EG", "ES", "UK", "EK", "ER", "EN", "ET", "EU", "FK", "FO", "FM", "FJ", "FI", "FR", "FG", "FP", "FS", "GB", "GA", "GZ", "GG", "GM", "GH", "GI", "GO", "GR", "GL", "GJ", "GP", "GQ", "GT", "GK", "GV", "PU", "GY", "HA", "HM", "HO", "HK", "HQ", "HU", "IC", "IN", "ID", "IR", "IZ", "EI", "IS", "IT", "JM", "JN", "JA", "DQ", "JE", "JQ", "JO", "JU", "KZ", "KE", "KQ", "KR", "KN", "KS", "KU", "KG", "LA", "LG", "LE", "LT", "LI", "LY", "LS", "LH", "LU", "MC", "MK", "MA", "MI", "MY", "MV", "ML", "MT", "IM", "RM", "MB", "MR", "MP", "MF", "MQ", "MD", "MN", "MG", "MJ", "MH", "MO", "MZ", "XM", "WA", "NR", "BQ", "NP", "NL", "NT", "NC", "NZ", "NU", "NG", "NI", "NE", "NF", "XN", "CQ", "NO", "MU", "OC", "PK", "LQ", "PS", "PM", "PP", "PF", "PA", "PE", "RP", "PC", "PL", "PO", "RQ", "QA", "RE", "RO", "RS", "RW", "WS", "SM", "TP", "SA", "XS", "SG", "RI", "SE", "SL", "SN", "XR", "LO", "SI", "BP", "SO", "SF", "SX", "SP", "PG", "CE", "SH", "SC", "ST", "SB", "VC", "SU", "NS", "SV", "WZ", "SW", "SZ", "SY", "TW", "TI", "TZ", "TH", "TO", "TL", "TN", "TD", "XT", "TE", "TS", "TU", "TX", "TK", "TV", "UG", "UP", "AE", "UY", "UZ", "NH", "VT", "VE", "VM", "VQ", "WQ", "XW", "WF", "WE", "WI", "YM", "YI", "ZA", "ZI"
PostalCd	string	Employee's Postal Code
W2FormData	object	Employee's Form W-2 information
B1Wages	number	Gets the total taxable wages, tips, and other compensation paid by the employer to employees during the year. These figures should be prior to payroll deductions. Size Range: 0-999999999.99
B2FedTaxWH	number	Gets the total federal income tax withheld from the employee's wages for the year. Include the 20% excise tax withheld on excess parachute payments. Size Range: 0-999999999.99
B3SocSecWages	number	Gets the total wages paid (before payroll deductions) subject to employee social security tax. Size Range: 0-999999999.99
B4SocSecTaxWH	number	Gets the total amount of social security tax withheld from employees. Include only taxes withheld for wages and tips. Size Range: 0-999999999.99
B5MediWages	number	Gets the amount of wages and tips subject to medicare tax. These are similar to those subject to social security tax (boxes 3 and 7) except that there is no wage base limit for Medicare tax. Size Range: 0-999999999.99
B6MediTaxWH	number	Gets the amount of taxes withheld from employees for Medicare tax Size Range: 0-999999999.99
B7SocSecTips	number	Gets the tips reported by the employee for which the employer did not have enough employee funds to collect the social security tax for the tips. Size Range: 0-999999999.99
B8AllocatedTips	number	Gets the tips allocated to your employee if you operate a large food or beverage establishment. Size Range: 0-999999999.99
B10DependtCareBenefits	number	Gets the total amount of dependent care benefits paid or incurred by the employer for employees under a dependent care assistance program. Size Range: 0-999999999.99
B11Sec457Plan	number	Gets the amount distributed to an employee from the employer's non-qualified plan Size Range: 0-999999999.99
B11NonSec457Plan	number	Gets the amount distributed to an employee from the employer's non-governmental section 457(b) plan Size Range: 0-999999999.99
B12aAmt	number	Enter the amount value for the code selected under Box 12a. Size Range: 0-999999999.99
B12bAmt	number	Enter the amount value for the code selected under Box 12b. Size Range: 0-999999999.99
B12cAmt	number	Enter the amount value for the code selected under Box 12c. Size Range: 0-999999999.99
B12dAmt	number	Enter the amount value for the code selected under Box 12d. Size Range: 0-999999999.99
B12aCd	string	Enter the Box 12a Code. Allowed values: "A", "B", "C", "D", "E", "F", "G", "H", "J", "K", "L", "M", "N", "P", "Q", "R", "S", "T", "V", "W", "Y", "Z", "AA", "BB", "CC", "DD", "EE", "FF", "GG", "HH"
B12bCd	string	Enter the Box 12b Code. Allowed values: "A", "B", "C", "D", "E", "F", "G", "H", "J", "K", "L", "M", "N", "P", "Q", "R", "S", "T", "V", "W", "Y", "Z", "AA", "BB", "CC", "DD", "EE", "FF", "GG", "HH"
B12cCd	string	Enter the Box 12c Code. Allowed values: "A", "B", "C", "D", "E", "F", "G", "H", "J", "K", "L", "M", "N", "P", "Q", "R", "S", "T", "V", "W", "Y", "Z", "AA", "BB", "CC", "DD", "EE", "FF", "GG", "HH"
B12dCd	string	Enter the Box 12d Code. Allowed values: "A", "B", "C", "D", "E", "F", "G", "H", "J", "K", "L", "M", "N", "P", "Q", "R", "S", "T", "V", "W", "Y", "Z", "AA", "BB", "CC", "DD", "EE", "FF", "GG", "HH"
B13IsStatEmp	Boolean	When true, identifies the statutory employees whose earnings are subject to social security and Medicare taxes but not subject to federal income tax withholding. They are independent contractors under the common-law rules but are treated by statute as employees.
B13IsRetPlan	Boolean	When true, identifies if the employee is an active participant of a retirement plan.
B13Is3rdPartySickPay	Boolean	When true, identifies if the business reports third-party sick pay.
B14Other	string	Gets any additional information that the employer wants to give to employees that cannot be reported in boxes 1-13. Examples include auto allowance, travel reimbursement, relocation expenses, job uniforms, after-tax employee contributions to an HSA, etc. Size Range: 1..51
ControlNum	string	Identifies individual Forms W-2 and this box is optional.
States	object[]	Contains list of state returns information.
B15StateCd	string	State Code of Employer's State. Size Range: 2 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"
B15StateIdNum	string	Identification Number of Employer's State. Size Range: ..20
B16StateWages	number	Amount of Wages, tips, etc for State. Size Range: 0-999999999.99
B17StateTax	number	Income Tax of State. Size Range: 0-999999999.99
LocalityData	object[]	Contains list of locality information about the state.
LocalWages	number	Amount of Local Wages, tips, etc for State. Size Range: 0-999999999.99
LocalTax	number	Local Income Tax of State. Size Range: 0-999999999.99
LocalityNm	string	Locality name of State.
TaxTypeCd	enum	Enter the Tax Type Code for the amount entered in "LocalWages" and "LocalTax". Allowed values: "C City Income Tax", "D County Income Tax", "E School District Income Tax", "F Other Income Tax"
County	enum	Enter the Indiana County code if the "TaxTypeCd" code is "D" - County Income Tax. Allowed values: "Adams", "Allen", "Bartholomew", "Benton", "Blackford", "Boone", "Brown", "Carrol", "Cass", "Clark", "Clay", "Clinton", "Crawford", "Daviess", "Dearborn", "Decatur", "DeKalb", "Delaware", "Dubois", "Elkhart", "Fayette", "Floyd", "Fountain", "Franklin", "Fulton", "Gibson", "Grant", "Greene", "Hamilton", "Hancock", "Harrison", "Hendricks", "Henry", "Howard", "Huntington", "Jackson", "Jasper", "Jay", "Jefferson", "Jennings", "Johnson", "Knox", "Kosciusko", "LaGrange", "Lake", "LaPorte", "Lawrence", "Madison", "Marion", "Marshall", "Martin", "Miami", "Monroe", "Montgomery", "Morgan", "Newton", "Noble", "Ohio", "Orange", "Owen", "Parke", "Perry", "Pike", "Porter", "Posey", "Pulaski", "Putnam", "Randolph", "Ripley", "Rush", "St.Joseph", "Scott", "Shelby", "Spencer", "Starke", "Steuben", "Sullivan", "Switzerland", "Tippecanoe", "Tipton", "Union", "Vanderburgh", "Vermillion", "Vigo", "Wabash", "Warren", "Warrick", "Washington", "Wayne", "Wells", "White", "Whitley"
SchoolDistrictNum	string	Enter the School District Number if the "TaxTypeCd" is "E" - School District Income Tax.
EmployeeStateSpecificData	object	Contains employee specific data for the selected states.
KS	object	Contains employee state specific data for Kansas.
EmployeeContribution	number	Enter the amount of Employee Contribution to KPERS, KP & F and Judges. Size Range: 0-999999999.99
ME	object	Contains employee state specific data for Maine.
MEPERScontribution	number	Enter the amount of pick-up contributions deducted from this employee’s salary and contributed to MEPERS on behalf of the employee. Size Range: 0-999999999.99
MD	object	Contains employee state specific data for Maryland.
W4ExemptionCount	int	Enter the number of exemptions claimed on Form W-4.
NJ	object	Contains employee state specific data for New Jersey.
PvtFmlLeaveInsuranceNum	string	Enter the Private Family Leave Insurance Plan Number. Size Range: ..14
FmlLeaveInsuranceWH	number	Enter the amount withheld as Family Leave Insurance workers contributions. Size Range: 0-999.99
PvtDisabilityPlanNum	string	Enter the Private Disability Plan Number. Size Range: ..14
DisabilityInsuranceWH	number	Enter the amount withheld as workers’ contributions for Disability Insurance. Size Range: 0-999.99
CombNJUnempInsWrkFrceDevProgHCSubWH	number	Enter the amount withheld as workers contributions for Combined NJ unemployment insurance, Workforce Development Program and health Care Subsidy. Size Range: 0-999.99
DeffCompAmt	number	Enter the total employee elective deferrals to a Code Section 401(k) plan, made during the year. Size Range: 0-9999999.99
IsRetirementPlan	Boolean	When TRUE, identifies that the employee was an active participant (for any part of the year) in a retirement plan.
OR	object	Contains employee state specific data for Oregon.
DateFirstEmployed	date	Enter the date first employed.
DateOfSeparation	date	Enter the date of separation.
TaxableWagesForStateTransitTax	number	Enter the State Taxable Wages for Statewide Transit Tax. Size Range: 0-999999999.99
StateTransitTaxWH	number	Enter the Statewide Transit Tax Withheld. Size Range: 0-999999999.99
MA	object	Contains employee state specific data for Massachusetts.
EeContributionMAPFML	number	Enter the Employee contribution for Paid Family and Medical Leave. Size Range: 0-999999999.99
StateReconData	object	Collects State Recon fields specific for each state. Click here, for the description of each state specific Recon fields.

Response Body

Field	Type	Description
StatusCode	number	Returns the HTTP status codes like 200,300 etc.
StatusName	string	Name of the status code
StatusMessage	string	Detailed status message
SubmissionId	Guid	Unique identifier of a submission
BusinessId	Guid	Unique identifier of a Business.
PayerRef	string	Unique identifier of a Payer.
FormW2Records	object	Pulls the Form W-2 records with Success and Error statuses
SuccessRecords	object[]	It will show the detailed information about the success status of Form W2 Records
SequenceId	string	An 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.
RecordId	Guid	An unique identifier generated by TaxBandits when a W2 return is created.
EmployeeId	Guid	An unique identifier generated by TaxBandits for a employee when a W2 return is created. You can use this id for your future reference to Update.
FederalReturn	object	Returns the record status and StatusTs of federal return.
Status	string	Returns the record status.
StatusTs	string	Returns date and time of return created.
Info	string	Returns information about the Federal Filing service.
StateReturns	object[]	Returns collection of state returns information
StateCd	string	Returns the state code of the state for which the return is filed.
Status	string	Returns the record status of the state return.
StatusTs	string	Date and time of the return created.
Info	string	Returns the information about the state for which we are not supporting state filing.
Errors	object[]	Shows error information of state returns of Form W2
Id	string	Returns the validation error Id.
Name	string	Name of the validation error.
Message	string	Description of the validation error.
Postal	object	Returns the status and StatusTs of postal mailing service for Form W2.
Status	string	Returns the status of postal order.
StatusTs	string	Returns the date and time of the postal order created.
Info	string	Returns the information about Postal mailing service.
OnlineAccess	object	Returns the Email address for whom the online access to be given and Status of online access.
Status	string	Returns the Status of the Online Access.
Email	string	Email address for whom the online access to be given.
Info	string	Information about the online access service.
ScheduleFiling	object	Returns the date of the schedule filing.
ScheduledOn	string	Date of the schedule filing to know when the return to be filed to the IRS.
Info	string	Information about Schedule Filing service.
ErrorRecords	object[]	It will show the detailed information about the error status of Form W2 Records.
SequenceId	string	An 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.
RecordId	Guid	Unique identifier of a record
Errors	object[]	Shows detailed error information
Id	string	Returns the validation error Id
Name	string	Name of the validation error
Message	string	Description of the validation error
Errors	object[]	Shows detailed error information
Id	string	Returns the validation error Id
Name	string	Name of the validation error
Message	string	Description of the validation error

Request JSON

{
 "SubmissionManifest": {
   "SubmissionId": null,
   "TaxYear": "2021",
   "IsFederalFiling": true,
   "IsStateFiling": true,
   "IsPostal": false,
   "IsOnlineAccess": true,
   "IsScheduleFiling": false,
   "ScheduleFiling": null
 },
 "ReturnHeader": {
   "Business": {
     "BusinessId": null,
     "PayerRef": "Pe123",
     "BusinessNm": "Brian LLC",
     "TradeNm": "Brian Corporate Services",
     "IsEIN": true,
     "EINorSSN": "426482784",
     "Email": "brianscott@gmail.com",
     "ContactNm": "Brian O Relly",
     "Phone": "1234447890",
     "PhoneExtn": "12345",
     "Fax": "4567893120",
     "BusinessType": "ESTE",
     "SigningAuthority": {
       "Name": "Altof",
       "Phone": "1234578960",
       "BusinessMemberType": "ADMINISTRATOR"
     },
     "KindOfEmployer": "FEDERALGOVT",
     "KindOfPayer": "REGULAR941",
     "IsBusinessTerminated": true,
     "IsForeign": true,
     "USAddress": {
       "Address1": "1751 Kinsey Rd",
       "Address2": "Main St",
       "City": "Dothan",
       "State": "AL",
       "ZipCd": "36303"
     },
     "ForeignAddress": {
       "Address1": "500 Penn Avenue",
       "Address2": "Park Street",
       "City": "Toronto",
       "ProvinceOrStateNm": "Ontario",
       "Country": "CA",
       "PostalCd": "02452"
     }
   }
 },
 "ReturnData": [
   {
     "RecordId": null,
     "SequenceId": "001",
     "Employee": {
       "EmployeeId": null,
       "SSN": "412-27-4749",
       "FirstNm": "Mianic6",
       "MiddleNm": "George",
       "LastNm": "Augustin",
       "Suffix": "Sr",
       "Email": "mike@gmail.com",
       "Fax": "4567891234",
       "Phone": "4259631478",
       "IsForeign": false,
       "USAddress": {
         "Address1": "1751 Kinsey Rd",
         "Address2": "Main St",
         "City": "Dothan",
         "State": "AL",
         "ZipCd": "36303"
       },
       "ForeignAddress": {
         "Address1": "500 Penn Avenue",
         "Address2": "Park Street",
         "City": "Toronto",
         "ProvinceOrStateNm": "Ontario",
         "Country": "CA",
         "PostalCd": "02452"
       }
     },
     "W2FormData": {
       "B1Wages": 50000.65,
       "B2FedTaxWH": 5263.32,
       "B3SocSecWages": 137000,
       "B4SocSecTaxWH": 46.15,
       "B5MediWages": 137700,
       "B6MediTaxWH": 78.21,
       "B7SocSecTips": 700,
       "B8AllocatedTips": 45,
       "B10DependtCareBenefits": 78,
       "B11Sec457Plan": 96,
       "B11NonSec457Plan": 0,
       "B12aCd": "EE",
       "B12aAmt": 32,
       "B12bCd": "B",
       "B12bAmt": 21,
       "B12cCd": "E",
       "B12cAmt": 213,
       "B12dCd": "H",
       "B12dAmt": 210,
       "B13IsStatEmp": true,
       "B13IsRetPlan": true,
       "B13Is3rdPartySickPay": true,
       "B14Other": "Real Estate 4500",
       "ControlNum": "35231",
       "States": [
         {
           "B15StateCd": "IN",
           "B15StateIdNum": "9999999999 999",
           "B16StateWages": 1000,
           "B17StateTax": 100,
           "LocalityData": [
             {
               "LocalWages": 300.23,
               "LocalTax": 100.45,
               "LocalityNm": "Pristine",
               "County": "adams",
               "TaxTypeCd": null,
               "SchoolDistrictNum": null
             }
           ]
         },
         {
           "B15StateCd": "VT",
           "B15StateIdNum": "WHT98765121",
           "B16StateWages": 500000.65,
           "B17StateTax": 5263.32,
           "LocalityData": [
             {
               "LocalWages": 300.23,
               "LocalTax": 100.45,
               "LocalityNm": "Pristine",
               "TaxTypeCd": null,
               "County": null,
               "SchoolDistrictNum": null
             }
           ]
         },
         {
           "B15StateCd": "PA",
           "B15StateIdNum": "99999999",
           "B16StateWages": 1000,
           "B17StateTax": 100,
           "LocalityData": [
             {
               "LocalWages": 300.23,
               "LocalTax": 100.45,
               "LocalityNm": "Pristine",
               "TaxTypeCd": null,
               "County": null,
               "SchoolDistrictNum": null
             }
           ]
         },
         {
           "B15StateCd": "KS",
           "B15StateIdNum": "036499993579F10",
           "B16StateWages": 50000.65,
           "B17StateTax": 0,
           "LocalityData": [
             {
               "LocalWages": 300.23,
               "LocalTax": 100.45,
               "LocalityNm": "Pristine",
               "TaxTypeCd": null,
               "County": null,
               "SchoolDistrictNum": null
             }
           ]
         }
       ],
       "EmployeeStateSpecificData": {
         "KS": {
           "EmployeeContribution": 251.55
         }
       }
     }
   }
 ],
 "StateReconData": {
   "IN": {
     "FormWH3": {
       "INWithHoldingID": "4657385932 254",
       "NumOfW2WH18W2G1099Forms": 23,
       "StateTaxWHW2WH18W2G1099": 100,
       "CountyTaxWHW2WH18W2G1099": 100,
       "TotTaxWH": 200,
       "TotDeposits": 500,
       "BalDue": 0,
       "OverPayment": 300,
       "CountyTaxWH": [
         {
           "CountyNm": "Adams",
           "TaxWH": 50
         },
         {
           "CountyNm": "Decatur",
           "TaxWH": 50
         }
       ],
       "TotCountyTaxWH": 100
     }
   },
   "VT": {
     "FormWHT434": {
       "VTWithHoldingID": "WHT98765101",
       "PayFreq": "Quarterly",
       "IsBusinessCeasedWantToCloseAcc": "True",
       "BusinessCeaseDate": "07/10/2021",
       "IsReportingSickPay": "True",
       "AggErHealthInsCoverage": 210,
       "TotNumOfW2Forms": 15,
       "TotWagesPerW2": 1000,
       "TaxWHPerW2": 200,
       "TotNumOf1099Forms": 16,
       "Tot1099Payments": 1000,
       "TaxWHPer1099": 201,
       "TotTaxWH": 401,
       "IsPaidPreparer": "True"
     }
   },
   "PA": {
     "FormREV1667": {
       "PAWithHoldingID": 45734565,
       "TotNumOfW2": 4,
       "TotNumOf1099R": 0,
       "TotNumOf1099NECMISC": 0,
       "TotWagesAndDistribution": 1000,
       "TotTaxWH": 0,
       "WagesAndDistribution": {
         "Qtr1": "100",
         "Qtr2": "100",
         "Qtr3": "100",
         "Qtr4": "700",
         "TotWagesAllQtrs": 1000
       },
       "TaxWH": {
         "Qtr1": "0",
         "Qtr2": "0",
         "Qtr3": "0",
         "Qtr4": "0",
         "TotTaxWHAllQtrs": 0
       }
     }
   },
   "KS": {
     "FormKW3": {
       "KSWithHoldingID": "036999999999F99",
       "WHAccClosedDate": null,
       "NumOf1099W2Forms": 1,
       "TotTaxWH1099W2": 100,
       "WHTaxPaid": 49,
       "CreditAvailable": 50,
       "TotWHPayment": 99,
       "Overpayment": 0,
       "BalanceDue": 1,
       "Penalty": 0,
       "Interest": 0,
       "TotTax": 1,
       "FilingSchType": "Quarterly",
       "Quarterly": {
         "Qtr1": 99,
         "Qtr2": 0,
         "Qtr3": 0,
         "Qtr4": 0
       },
       "Monthly": null,
       "SemiMonthly": null,
       "QuadMonthly": null,
       "Annual": null,
       "TotPayments": 99
     }
   }
 }
}

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
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277

Response JSON

{
 "StatusCode": 200,
 "StatusName": "Ok",
 "StatusMessage": "Successful API call",
 "SubmissionId": "ef869fda-5562-41c8-b0d2-b61ef19a2f5a",
 "BusinessId": "668e8869-ef32-4292-a9a7-b44c097647e5",
 "PayerRef": "Pe123",
 "FormW2Records": {
   "SuccessRecords": [
     {
       "SequenceId": "001",
       "RecordId": "566e1623-3c07-4d15-9fcc-00cad9a3a5d5",
       "EmployeeId": "efee6e99-e861-48fb-9c82-61d0f9e0c97f",
       "FederalReturn": {
         "Status": "CREATED",
         "StatusTs": "2021-08-06 10:19:05 -04:00",
         "Info": null
       },
       "StateReturns": [
         {
           "StateCd": "IN",
           "Status": "CREATED",
           "StatusTs": "2021-08-06 10:19:05 -04:00",
           "Info": null,
           "Errors": null
         },
         {
           "StateCd": "VT",
           "Status": "CREATED",
           "StatusTs": "2021-08-06 10:19:05 -04:00",
           "Info": null,
           "Errors": null
         },
         {
           "StateCd": "PA",
           "Status": "CREATED",
           "StatusTs": "2021-08-06 10:19:05 -04:00",
           "Info": null,
           "Errors": null
         },
         {
           "StateCd": "KS",
           "Status": "CREATED",
           "StatusTs": "2021-08-06 10:19:05 -04:00",
           "Info": null,
           "Errors": null
         }
       ],
       "Postal": null,
       "OnlineAccess": {
           "Status": "CREATED",
           "Email": "john@gmail.com",
          "Info": null
       },
       "ScheduleFiling": null
     }
   ],
   "ErrorRecords": null
 },
 "Errors": null
}

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

# Delete

Delete API Endpoint, as the name suggests, is used to delete the Tax Return that was created. Once the return is transmitted, the tax return can not be deleted.

DELETE FormW2/Delete

Request Body

Field	Type	Description
SubmissionId	guid	Unique identifier of a submission
RecordIds	Guid[]	An unique identifier generated by TaxBandits when a W2 return is created. Mention the W2 return's Record ID that you want to delete.

Response Body

Field	Type	Description
StatusCode	number	Returns the HTTP status codes like 200,300 etc.
StatusName	string	Name of the status code
StatusMessage	string	Detailed status message
SubmissionId	Guid	Unique identifier of a submission
FormW2Records	object	Pulls the Form W-2 records with Success and Error statuses
SuccessRecords	object[]	It will show the detailed information about the success status of Form W2 Records
SequenceId	string	An 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.
RecordId	Guid	Unique identifier of a record
Status	string	Returns the status of the records.
StatusTs	string	Date and time of return deleted.
StateReturns	object[]	Returns the state code and return status.
StateCode	string	Returns the code of the state.
RecordStatus	string	Returns the status of the records.
ErrorRecords	object[]	It will show the detailed information about the error status of Form W2 Records.
RecordId	Guid	Unique identifier of a record
SequenceId	string	An 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.
Errors	object[]	Shows detailed error information
Id	string	Returns the validation error id
Name	string	Name of the validation error
Message	string	Description of the validation error
Errors	object[]	Shows detailed error information
Id	string	Returns the validation error Id
Name	string	Name of the validation error
Message	string	Description of the validation error

Request JSON

FormW2/Delete?SubmissionId=3cf6c6a3-2e91-4906-8f90-4bcc1b0c5465&RecordIds=212a2a80-f74a-4af9-b034-782e8650fe37,50013b2d-01ff-41b1-b08b-dbf8940a8a7c

Response JSON

{
   "StatusCode": 200,
   "StatusName": "Ok",
   "StatusMessage": "Successful API call",
   "SubmissionId": "3cf6c6a3-2e91-4906-8f90-4bcc1b0c5465",
   "FormW2Records": {
       "SuccessRecords": [
           {
               "SequenceId": "1",
               "RecordId": "212a2a80-f74a-4af9-b034-782e8650fe37",
               "Status": "DELETED",
               "StatusTs": "2021-08-05 09:53:23 -04:00",
               "StateReturns": null
           },
           {
               "SequenceId": "1",
               "RecordId": "50013b2d-01ff-41b1-b08b-dbf8940a8a7c",
               "Status": "DELETED",
               "StatusTs": "2021-08-05 09:53:23 -04:00",
               "StateReturns": null
           }
       ],
       "ErrorRecords": null
   },
   "Errors": null
}

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

# Get

GET endpoint can be used to fetch the complete details of a submission in whole or individual records. It requires the Submission ID as a parameter & Record ID(s) as optional parameter.

GET FormW2/Get

Request Body

Field	Type	Description
SubmissionId	guid	Unique identifier of a submission
RecordIds	Guid[]	An unique identifier generated by TaxBandits when a W2 return is created. Mention the W2 return's Record ID that you want to fetch data.

Response Body

Field	Type	Description
StatusCode	number	Returns the HTTP status codes like 200,300 etc.
StatusName	string	Name of the status code.
StatusMessage	string	Detailed status message.
FormW2Records	object	Pulls the submission and record details.
SubmissionId	Guid	Unique identifier created by TaxBandits for each submission. Not required when you are creating a return.
TaxYear	string	Tax year of Form W2 to be filed. Allowed values: "2021"
IsFederalFiling	Boolean	Federal Filing for the return will be enabled when the value is True. Form W2 will be sent directly to the IRS.
IsStateFiling	Boolean	State Filing for the return will be enabled when the value is True. Form W2 will be directly filed with the respective employee states. Note: State Filing will not be created for the states that do not require State filing.
IsPostal	Boolean	Postal Order will be created when the value is set as True. Once the return is Transmitted, Form W2 employee copies will be postal mailed to the employee's address via USPS. Note: Postal Orders for Foreign Address will not be created.
IsOnlineAccess	Boolean	Online Access will be enabled when the value is set as True. Once the return is Transmitted, an email with the link to the secure TaxBandits portal will be sent to the employee. The employee can provide consent and download Form W2 employee copies from the portal.
IsScheduleFiling	Boolean	When true, schedule filing services will be provided for W2 returns under this submission.
ScheduleFiling	object	Contains preferred date to submit the returns to the IRS. Required only when "IsScheduleFiling" is True .
EfileDate	string	Returns date of schedule filing.
ReturnHeader	object	Contains information about the Business details.
Business	object	Object to identify the Business Details.
BusinessId	Guid	Returns the unique Business ID for the Business. It can be used in future to refer the same business.
PayerRef	string	Unique identifier of the payer. Size Range: ..50
BusinessNm	string	Name of the business Size Range: ..75
TradeNm	string	Name under which the business operates Size Range: ..75
IsEIN	Boolean	When true, identifies the business with an EIN.
EINorSSN	string	Returns the Employer Identification Number of Business Size Range: 9
Email	string	Email address of the Business Size Range: ..40
ContactNm	string	Name of the person who can be contacted by the IRS Size Range: ..27
Phone	string	Phone number of the business Size Range: 10
PhoneExtn	string	Extension of the business phone number Size Range: ..5
Fax	string	Fax number of the Business Size Range: 10
BusinessType	string	Type of business. Optional for W-2/1099 and mandatory for 94X series Size Range: 4 Allowed values: "ESTE", "PART", "CORP", "EORG", "SPRO"
SigningAuthority	object	Details of the person who is authorized to sign the return
Name	string	Name of the signing authority Size Range: ..35
Phone	string	Phone number of the signing authority Size Range: 10
BusinessMemberType	string	Business title of the signing authority Size Range: 5..29 Allowed values: "CORPORATESECRETARY", "SECRETARYTREASURER", "PARTNER", "GENERALPARTNER", "LIMITEDPARTNER", "LLCMEMBER", "MANAGINGMEMBER", "MANAGER", "TAXMATTERPARTNER", "PRESIDENT", "VICEPRESIDENT", "CORPORATETREASURER", "TREASURER", "ASSISTANTTREASURER", "CHIEFACCOUNTINGOFFICER", "CHIEFEXECUTIVEOFFICER", "CHIEFFINANCIALOFFICER", "TAXOFFICER", "CHIEFOPERATINGOFFICER", "CORPORATEOFFICER", "EXECUTIVEDIRECTOR", "DIRECTOR", "CHAIRMAN", "EXECUTIVEADMINISTRATOR", "RECEIVER", "PASTOR", "ASSISTANTTORELIGIOUSLEADER", "REVEREND", "PRIEST", "MINISTER", "RABBI", "LEADEROFRELIGIOUSORGANIZATION", "SECRETARY", "DIRECTOROFTAXATION", "DIRECTOROFPERSONNEL", "ADMINISTRATOR", "EXECUTOR", "TRUSTEE", "FIDUCIARY", "OWNER", "SOLEPROPRIETOR", "MEMBER", "SOLEMEMBER"
KindOfEmployer	string	Identifies the kind of employer. Mandatory for W-2 and optional for 1099-MISC and 94X series Allowed values: "FEDERALGOVT", "STATEORLOCAL501C", "NONGOVT501C", "STATEORLOCALNON501C", "NONEAPPLY"
KindOfPayer	string	Identifies the kind of payer. This field is mandatory in W-2 and optional in 1099-MISC and 94X series Allowed values: "REGULAR941", "REGULAR944", "AGRICULTURAL943", "HOUSEHOLD", "MILITARY", "MEDICAREQUALGOVEM", "RAILROADFORMCT1"
IsBusinessTerminated	Boolean	When true, identifies the business as terminated.
IsForeign	Boolean	When true, identifies the business address with a foreign address.
USAddress	object	If IsForeign is false, pass US address of the business
Address1	string	Employer/Payer's US address (street address or post office box of that locality) Size Range: ..35
Address2	string	Employer/Payer's suite or apartment Size Range: ..35
City	string	Employer/Payer's city Size Range: ..27
State	string	Employer/Payer's state code. Refer Static values. Size Range: 2 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"
ZipCd	string	Employer/Payer's zip code
ForeignAddress	object	If IsForeign is true, pass foreign address of the business
Address1	string	Employer/Payer's foreign address (street address or post office box of that locality) Size Range: ..35
Address2	string	Employer/Payer's suite or apartment Size Range: ..35
City	string	Employer/Payer's city Size Range: ..27
ProvinceOrStateNm	string	Employer/Payer's province or state name Size Range: ..30
Country	string	Employer/Payer's country Size Range: 2 Allowed values: "US", "CA", "MX", "AF", "AX", "XI", "AL", "AG", "AQ", "AN", "AO", "AV", "AY", "AC", "AR", "AM", "AA", "XA", "AT", "AS", "AU", "AJ", "XZ", "BF", "BA", "FQ", "BG", "BB", "BS", "BO", "BE", "BH", "BN", "BD", "BT", "BL", "BK", "BC", "BV", "BR", "IO", "VI", "BX", "BU", "UV", "BM", "BY", "CB", "CM", "XY", "CV", "CJ", "CT", "CD", "XC", "CI", "CH", "KT", "IP", "CK", "CO", "CN", "CF", "CG", "CW", "CR", "VP", "CS", "IV", "HR", "CU", "CY", "EZ", "DA", "DX", "DJ", "DO", "DR", "TT", "EC", "EG", "ES", "UK", "EK", "ER", "EN", "ET", "EU", "FK", "FO", "FM", "FJ", "FI", "FR", "FG", "FP", "FS", "GB", "GA", "GZ", "GG", "GM", "GH", "GI", "GO", "GR", "GL", "GJ", "GP", "GQ", "GT", "GK", "GV", "PU", "GY", "HA", "HM", "HO", "HK", "HQ", "HU", "IC", "IN", "ID", "IR", "IZ", "EI", "IS", "IT", "JM", "JN", "JA", "DQ", "JE", "JQ", "JO", "JU", "KZ", "KE", "KQ", "KR", "KN", "KS", "KU", "KG", "LA", "LG", "LE", "LT", "LI", "LY", "LS", "LH", "LU", "MC", "MK", "MA", "MI", "MY", "MV", "ML", "MT", "IM", "RM", "MB", "MR", "MP", "MF", "MQ", "MD", "MN", "MG", "MJ", "MH", "MO", "MZ", "XM", "WA", "NR", "BQ", "NP", "NL", "NT", "NC", "NZ", "NU", "NG", "NI", "NE", "NF", "XN", "CQ", "NO", "MU", "OC", "PK", "LQ", "PS", "PM", "PP", "PF", "PA", "PE", "RP", "PC", "PL", "PO", "RQ", "QA", "RE", "RO", "RS", "RW", "WS", "SM", "TP", "SA", "XS", "SG", "RI", "SE", "SL", "SN", "XR", "LO", "SI", "BP", "SO", "SF", "SX", "SP", "PG", "CE", "SH", "SC", "ST", "SB", "VC", "SU", "NS", "SV", "WZ", "SW", "SZ", "SY", "TW", "TI", "TZ", "TH", "TO", "TL", "TN", "TD", "XT", "TE", "TS", "TU", "TX", "TK", "TV", "UG", "UP", "AE", "UY", "UZ", "NH", "VT", "VE", "VM", "VQ", "WQ", "XW", "WF", "WE", "WI", "YM", "YI", "ZA", "ZI"
PostalCd	string	Employer/Payer's postal code
ReturnData	object[]	Contains information about the employee details and Form W2 details.
SequenceId	string	An 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
RecordId	Guid	Unique identifier of a record. Not required when you are creating a return.
Employee	object	Object to identify the employee details.
EmployeeId	Guid	An unique ID generated by TaxBandits after the return is created and will be returned in the Response. You can use this id for your future reference to Update.
SSN	string	Employee's Social Security Number (SSN) Size Range: 9
FirstNm	string	Employee's first name.
MiddleNm	string	Employee's middle name.
LastNm	string	Employee's last name.
Suffix	string	Employee's suffix. Allowed values: "Jr", "Sr", "I", "II", "III", "IV", "V", "VI", "VII"
Email	string	Employee's email address. Size Range: 0..40
Fax	string	Employee's fax number. Size Range: 10
Phone	string	Employee's phone number including area code. Size Range: 10
IsForeign	Boolean	When true, identifies the employee address with a foreign address.
USAddress	object	Object to identify the employee's US address
Address1	string	Employee's US address (street address or post office box of that locality) Size Range: ..35
Address2	string	Employee's suite or apartment Size Range: ..35
City	string	Employee's city Size Range: ..27
State	string	Employee's State code. Refer Static values. Size Range: 2 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"
ZipCd	string	Employee's zip code
ForeignAddress	object	If IsForeign is true, pass foreign address of the employee
Address1	string	Employee's foreign address (street address or post office box of that locality) Size Range: ..35
Address2	string	Employee's suite or apartment Size Range: ..35
City	string	Employee's city. Size Range: ..27
ProvinceOrStateNm	string	Employee's Province or State Name. Size Range: ..30
Country	string	Employee's country code. Refer Static values. Size Range: 2 Allowed values: "US", "CA", "MX", "AF", "AX", "XI", "AL", "AG", "AQ", "AN", "AO", "AV", "AY", "AC", "AR", "AM", "AA", "XA", "AT", "AS", "AU", "AJ", "XZ", "BF", "BA", "FQ", "BG", "BB", "BS", "BO", "BE", "BH", "BN", "BD", "BT", "BL", "BK", "BC", "BV", "BR", "IO", "VI", "BX", "BU", "UV", "BM", "BY", "CB", "CM", "XY", "CV", "CJ", "CT", "CD", "XC", "CI", "CH", "KT", "IP", "CK", "CO", "CN", "CF", "CG", "CW", "CR", "VP", "CS", "IV", "HR", "CU", "CY", "EZ", "DA", "DX", "DJ", "DO", "DR", "TT", "EC", "EG", "ES", "UK", "EK", "ER", "EN", "ET", "EU", "FK", "FO", "FM", "FJ", "FI", "FR", "FG", "FP", "FS", "GB", "GA", "GZ", "GG", "GM", "GH", "GI", "GO", "GR", "GL", "GJ", "GP", "GQ", "GT", "GK", "GV", "PU", "GY", "HA", "HM", "HO", "HK", "HQ", "HU", "IC", "IN", "ID", "IR", "IZ", "EI", "IS", "IT", "JM", "JN", "JA", "DQ", "JE", "JQ", "JO", "JU", "KZ", "KE", "KQ", "KR", "KN", "KS", "KU", "KG", "LA", "LG", "LE", "LT", "LI", "LY", "LS", "LH", "LU", "MC", "MK", "MA", "MI", "MY", "MV", "ML", "MT", "IM", "RM", "MB", "MR", "MP", "MF", "MQ", "MD", "MN", "MG", "MJ", "MH", "MO", "MZ", "XM", "WA", "NR", "BQ", "NP", "NL", "NT", "NC", "NZ", "NU", "NG", "NI", "NE", "NF", "XN", "CQ", "NO", "MU", "OC", "PK", "LQ", "PS", "PM", "PP", "PF", "PA", "PE", "RP", "PC", "PL", "PO", "RQ", "QA", "RE", "RO", "RS", "RW", "WS", "SM", "TP", "SA", "XS", "SG", "RI", "SE", "SL", "SN", "XR", "LO", "SI", "BP", "SO", "SF", "SX", "SP", "PG", "CE", "SH", "SC", "ST", "SB", "VC", "SU", "NS", "SV", "WZ", "SW", "SZ", "SY", "TW", "TI", "TZ", "TH", "TO", "TL", "TN", "TD", "XT", "TE", "TS", "TU", "TX", "TK", "TV", "UG", "UP", "AE", "UY", "UZ", "NH", "VT", "VE", "VM", "VQ", "WQ", "XW", "WF", "WE", "WI", "YM", "YI", "ZA", "ZI"
PostalCd	string	Employee's Postal Code
W2FormData	object	Employee's Form W-2 information
B1Wages	number	Gets the total taxable wages, tips, and other compensation paid by the employer to employees during the year. These figures should be prior to payroll deductions. Size Range: 0-999999999.99
B2FedTaxWH	number	Gets the total federal income tax withheld from the employee's wages for the year. Include the 20% excise tax withheld on excess parachute payments. Size Range: 0-999999999.99
B3SocSecWages	number	Gets the total wages paid (before payroll deductions) subject to employee social security tax. Size Range: 0-999999999.99
B4SocSecTaxWH	number	Gets the total amount of social security tax withheld from employees. Include only taxes withheld for wages and tips. Size Range: 0-999999999.99
B5MediWages	number	Gets the amount of wages and tips subject to medicare tax. These are similar to those subject to social security tax (boxes 3 and 7) except that there is no wage base limit for Medicare tax. Size Range: 0-999999999.99
B6MediTaxWH	number	Gets the amount of taxes withheld from employees for Medicare tax Size Range: 0-999999999.99
B7SocSecTips	number	Gets the tips reported by the employee for which the employer did not have enough employee funds to collect the social security tax for the tips. Size Range: 0-999999999.99
B8AllocatedTips	number	Gets the tips allocated to your employee if you operate a large food or beverage establishment. Size Range: 0-999999999.99
B10DependtCareBenefits	number	Gets the total amount of dependent care benefits paid or incurred by the employer for employees under a dependent care assistance program. Size Range: 0-999999999.99
B11Sec457Plan	number	Gets the amount distributed to an employee from the employer's non-qualified plan Size Range: 0-999999999.99
B11NonSec457Plan	number	Gets the amount distributed to an employee from the employer's non-governmental section 457(b) plan Size Range: 0-999999999.99
B12aAmt	number	The amount value for the code selected under Box 12a. Size Range: 0-999999999.99
B12bAmt	number	The amount value for the code selected under Box 12b. Size Range: 0-999999999.99
B12cAmt	number	The amount value for the code selected under Box 12c. Size Range: 0-999999999.99
B12dAmt	number	The amount value for the code selected under Box 12d. Size Range: 0-999999999.99
B12aCd	string	The Box 12a Code. Allowed values: "A", "B", "C", "D", "E", "F", "G", "H", "J", "K", "L", "M", "N", "P", "Q", "R", "S", "T", "V", "W", "Y", "Z", "AA", "BB", "CC", "DD", "EE", "FF", "GG", "HH"
B12bCd	string	The Box 12b Code. Allowed values: "A", "B", "C", "D", "E", "F", "G", "H", "J", "K", "L", "M", "N", "P", "Q", "R", "S", "T", "V", "W", "Y", "Z", "AA", "BB", "CC", "DD", "EE", "FF", "GG", "HH"
B12cCd	string	The Box 12c Code. Allowed values: "A", "B", "C", "D", "E", "F", "G", "H", "J", "K", "L", "M", "N", "P", "Q", "R", "S", "T", "V", "W", "Y", "Z", "AA", "BB", "CC", "DD", "EE", "FF", "GG", "HH"
B12dCd	string	The Box 12d Code. Allowed values: "A", "B", "C", "D", "E", "F", "G", "H", "J", "K", "L", "M", "N", "P", "Q", "R", "S", "T", "V", "W", "Y", "Z", "AA", "BB", "CC", "DD", "EE", "FF", "GG", "HH"
B13IsStatEmp	Boolean	When true, identifies the statutory employees whose earnings are subject to social security and Medicare taxes but not subject to federal income tax withholding. They are independent contractors under the common-law rules but are treated by statute as employees.
B13IsRetPlan	Boolean	When true, identifies if the employee is an active participant of a retirement plan.
B13Is3rdPartySickPay	Boolean	When true, identifies if the business reports third-party sick pay.
B14Other	string	Gets any additional information that the employer wants to give to employees that cannot be reported in boxes 1-13. Examples include auto allowance, travel reimbursement, relocation expenses, job uniforms, after-tax employee contributions to an HSA, etc. Size Range: 1..51
ControlNum	string	Identifies individual Forms W-2 and this box is optional.
States	object[]	Contains list of state returns information.
B15StateCd	string	State Code of Employer's State. Size Range: 2 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"
B15StateIdNum	string	Identification Number of Employer's State. Size Range: ..20
B16StateWages	number	Amount of Wages, tips, etc for State. Size Range: 0-999999999.99
B17StateTax	number	Income Tax of State. Size Range: 0-999999999.99
LocalityData	object[]	Contains list of locality information about the state.
LocalWages	number	Amount of Local Wages, tips, etc for State. Size Range: 0-999999999.99
LocalTax	number	Local Income Tax of State. Size Range: 0-999999999.99
LocalityNm	string	Locality name of State.
TaxTypeCd	enum	Enter the Tax Type Code for the amount entered in "LocalWages" and "LocalTax". Allowed values: "C City Income Tax", "D County Income Tax", "E School District Income Tax", "F Other Income Tax"
County	enum	Enter the Indiana County code if the "TaxTypeCd" code is "D" - County Income Tax. Allowed values: "Adams", "Allen", "Bartholomew", "Benton", "Blackford", "Boone", "Brown", "Carrol", "Cass", "Clark", "Clay", "Clinton", "Crawford", "Daviess", "Dearborn", "Decatur", "DeKalb", "Delaware", "Dubois", "Elkhart", "Fayette", "Floyd", "Fountain", "Franklin", "Fulton", "Gibson", "Grant", "Greene", "Hamilton", "Hancock", "Harrison", "Hendricks", "Henry", "Howard", "Huntington", "Jackson", "Jasper", "Jay", "Jefferson", "Jennings", "Johnson", "Knox", "Kosciusko", "LaGrange", "Lake", "LaPorte", "Lawrence", "Madison", "Marion", "Marshall", "Martin", "Miami", "Monroe", "Montgomery", "Morgan", "Newton", "Noble", "Ohio", "Orange", "Owen", "Parke", "Perry", "Pike", "Porter", "Posey", "Pulaski", "Putnam", "Randolph", "Ripley", "Rush", "St.Joseph", "Scott", "Shelby", "Spencer", "Starke", "Steuben", "Sullivan", "Switzerland", "Tippecanoe", "Tipton", "Union", "Vanderburgh", "Vermillion", "Vigo", "Wabash", "Warren", "Warrick", "Washington", "Wayne", "Wells", "White", "Whitley"
SchoolDistrictNum	string	Enter the School District Number if the "TaxTypeCd" is "E" - School District Income Tax.
EmployeeStateSpecificData	object	Contains employee specific data for the selected states.
KS	object	Contains employee state specific data for Kansas.
EmployeeContribution	number	Enter the amount of Employee Contribution to KPERS, KP & F and Judges. Size Range: 0-999999999.99
ME	object	Contains employee state specific data for Maine.
MEPERScontribution	number	Enter the amount of pick-up contributions deducted from this employee’s salary and contributed to MEPERS on behalf of the employee. Size Range: 0-999999999.99
MD	object	Contains employee state specific data for Maryland.
W4ExemptionCount	int	Enter the number of exemptions claimed on Form W-4.
NJ	object	Contains employee state specific data for New Jersey.
PvtFmlLeaveInsuranceNum	string	Enter the Private Family Leave Insurance Plan Number. Size Range: ..14
FmlLeaveInsuranceWH	number	Enter the amount withheld as Family Leave Insurance workers contributions. Size Range: 0-999.99
PvtDisabilityPlanNum	string	Enter the Private Disability Plan Number. Size Range: ..14
DisabilityInsuranceWH	number	Enter the amount withheld as workers’ contributions for Disability Insurance. Size Range: 0-999.99
CombNJUnempInsWrkFrceDevProgHCSubWH	number	Enter the amount withheld as workers contributions for Combined NJ unemployment insurance, Workforce Development Program and health Care Subsidy. Size Range: 0-999.99
DeffCompAmt	number	Enter the total employee elective deferrals to a Code Section 401(k) plan, made during the year. Size Range: 0-9999999.99
IsRetirementPlan	Boolean	When TRUE, identifies that the employee was an active participant (for any part of the year) in a retirement plan.
OR	object	Contains employee state specific data for Oregon.
DateFirstEmployed	date	Enter the date first employed.
DateOfSeparation	date	Enter the date of separation.
TaxableWagesForStateTransitTax	number	Enter the State Taxable Wages for Statewide Transit Tax. Size Range: 0-999999999.99
StateTransitTaxWH	number	Enter the Statewide Transit Tax Withheld. Size Range: 0-999999999.99
MA	object	Contains employee state specific data for Massachusetts.
EeContributionMAPFML	number	Enter the Employee contribution for Paid Family and Medical Leave. Size Range: 0-999999999.99
StateReconData	object	Collects State Recon fields specific for each state. Click here, for the description of each state specific Recon fields.
Errors	object[]	Shows detailed error information
Id	string	Returns the validation error Id
Name	string	Name of the validation error
Message	string	Description of the validation error

Request JSON

FormW2/Get?SubmissionId=ef869fda-5562-41c8-b0d2-b61ef19a2f5a&RecordIds=566e1623-3c07-4d15-9fcc-00cad9a3a5d5

Response JSON

{
"StatusCode": 200,
"StatusName": "Ok",
"StatusMessage": "Successful API call",
"FormW2Records": {
  "SubmissionManifest": {
    "SubmissionId": "ef869fda-5562-41c8-b0d2-b61ef19a2f5a",
    "TaxYear": "2021",
    "IsFederalFiling": true,
    "IsStateFiling": true,
    "IsPostal": false,
    "IsOnlineAccess": true,
    "IsScheduleFiling": false,
    "ScheduleFiling": null
  },
  "ReturnHeader": {
    "Business": {
      "BusinessId": "668e8869-ef32-4292-a9a7-b44c097647e5",
      "PayerRef": "Pe123",
      "BusinessNm": "Brian LLC",
      "TradeNm": "Brian Corporate Services",
      "IsEIN": true,
      "EINorSSN": "42-6482784",
      "Email": "brianscott@gmail.com",
      "ContactNm": "Brian O Relly",
      "Phone": "(123) 444-7890",
      "PhoneExtn": "12345",
      "Fax": "(456) 789-3120",
      "BusinessType": "ESTE",
      "SigningAuthority": {
        "Name": "Altof",
        "Phone": "(123) 457-8960",
        "BusinessMemberType": "ADMINISTRATOR"
      },
      "KindOfEmployer": "FEDERALGOVT",
      "KindOfPayer": "REGULAR941",
      "IsBusinessTerminated": true,
      "IsForeign": true,
      "USAddress": null,
      "ForeignAddress": {
        "Address1": "500 Penn Avenue",
        "Address2": "Park Street",
        "City": "Toronto",
        "ProvinceOrStateNm": "Ontario",
        "Country": "CA",
        "PostalCd": "02452"
      }
    }
  },
  "ReturnData": [
    {
      "RecordId": "566e1623-3c07-4d15-9fcc-00cad9a3a5d5",
      "SequenceId": "001",
      "Employee": {
        "EmployeeId": "efee6e99-e861-48fb-9c82-61d0f9e0c97f",
        "SSN": "412-27-4749",
        "FirstNm": "Mianic6",
        "MiddleNm": "George",
        "LastNm": "Augustin",
        "Suffix": "Sr",
        "Email": "mike@gmail.com",
        "Fax": "4567891234",
        "Phone": "4259631478",
        "IsForeign": false,
        "USAddress": {
          "Address1": "1751 Kinsey Rd",
          "Address2": "Main St",
          "City": "Dothan",
          "State": "AL",
          "ZipCd": "36303"
        },
        "ForeignAddress": null
      },
      "W2FormData": {
        "B1Wages": 50000.65,
        "B2FedTaxWH": 5263.32,
        "B3SocSecWages": 137000,
        "B4SocSecTaxWH": 46.15,
        "B5MediWages": 137700,
        "B6MediTaxWH": 78.21,
        "B7SocSecTips": 700,
        "B8AllocatedTips": 45,
        "B10DependtCareBenefits": 78,
        "B11Sec457Plan": 96,
        "B11NonSec457Plan": 0,
        "B12aCd": "EE",
        "B12aAmt": 32,
        "B12bCd": "B",
        "B12bAmt": 21,
        "B12cCd": "E",
        "B12cAmt": 213,
        "B12dCd": "H",
        "B12dAmt": 210,
        "B13IsStatEmp": true,
        "B13IsRetPlan": true,
        "B13Is3rdPartySickPay": true,
        "B14Other": "Real Estate 4500",
        "ControlNum": "35231",
        "States": [
          {
            "B15StateCd": "IN",
            "B16StateWages": 1000,
            "B15StateIdNum": "9999999999 999",
            "B17StateTax": 100,
            "LocalityData": [
              {
                "LocalWages": 300.23,
                "LocalTax": 100.45,
                "LocalityNm": "Pristine",
                "TaxTypeCd": null,
                "County": "ADAMS",
                "SchoolDistrictNum": null
              }
            ]
          },
          {
            "B15StateCd": "VT",
            "B16StateWages": 500000.65,
            "B15StateIdNum": "WHT98765121",
            "B17StateTax": 5263.32,
            "LocalityData": [
              {
                "LocalWages": 300.23,
                "LocalTax": 100.45,
                "LocalityNm": "Pristine",
                "TaxTypeCd": null,
                "County": null,
                "SchoolDistrictNum": null
              }
            ]
          },
          {
            "B15StateCd": "PA",
            "B16StateWages": 1000,
            "B15StateIdNum": "99999999",
            "B17StateTax": 100,
            "LocalityData": [
              {
                "LocalWages": 300.23,
                "LocalTax": 100.45,
                "LocalityNm": "Pristine",
                "TaxTypeCd": null,
                "County": null,
                "SchoolDistrictNum": null
              }
            ]
          },
          {
            "B15StateCd": "KS",
            "B16StateWages": 50000.65,
            "B15StateIdNum": "036499993579F10",
            "B17StateTax": 0,
            "LocalityData": [
              {
                "LocalWages": 300.23,
                "LocalTax": 100.45,
                "LocalityNm": "Pristine",
                "TaxTypeCd": null,
                "County": null,
                "SchoolDistrictNum": null
              }
            ]
          }
        ],
        "EmployeeStateSpecificData": {
          "ME": null,
          "OR": null,
          "MA": null,
          "KS": {
            "EmployeeContribution": 251.55
          },
          "NJ": null,
          "MD": null
        }
      }
    }
  ],
  "StateReconData": {
    "AL": null,
    "ID": null,
    "CT": null,
    "GA": null,
    "LA": null,
    "MO": null,
    "KS": {
      "FormKW3": {
        "KSWithHoldingID": "036999999999F99",
        "WHAccClosedDate": null,
        "NumOf1099W2Forms": 1,
        "TotTaxWH1099W2": 100,
        "WHTaxPaid": 49,
        "CreditAvailable": 50,
        "TotWHPayment": 99,
        "Overpayment": 0,
        "BalanceDue": 1,
        "Penalty": 0,
        "Interest": 0,
        "TotTax": 1,
        "FilingSchType": "QUARTERLY",
        "Annual": null,
        "Quarterly": {
          "Qtr1": 99,
          "Qtr2": 0,
          "Qtr3": 0,
          "Qtr4": 0
        },
        "Monthly": null,
        "SemiMonthly": null,
        "QuadMonthly": null,
        "TotPayments": 99
      }
    },
    "NJ": null,
    "MD": null,
    "PA": {
      "FormREV1667": {
        "PAWithHoldingID": "45734565",
        "TotNumOfW2": 4,
        "TotNumOf1099R": 0,
        "TotNumOf1099NECMISC": 0,
        "TotWagesAndDistribution": 1000,
        "TotTaxWH": 0,
        "WagesAndDistribution": {
          "Qtr1": 100,
          "Qtr2": 100,
          "Qtr3": 100,
          "Qtr4": 700,
          "TotWagesAllQtrs": 1000
        },
        "TaxWH": {
          "Qtr1": 0,
          "Qtr2": 0,
          "Qtr3": 0,
          "Qtr4": 0,
          "TotTaxWHAllQtrs": 0
        }
      }
    },
    "WV": null,
    "VT": {
      "FormWHT434": {
        "VTWithHoldingID": "WHT98765101",
        "PayFreq": "Quarterly",
        "IsBusinessCeasedWantToCloseAcc": true,
        "BusinessCeaseDate": "07/10/2021",
        "IsReportingSickPay": true,
        "AggErHealthInsCoverage": 210,
        "TotNumOfW2Forms": 15,
        "TotWagesPerW2": 1000,
        "TaxWHPerW2": 200,
        "TotNumOf1099Forms": 16,
        "Tot1099Payments": 1000,
        "TaxWHPer1099": 201,
        "TotTaxWH": 401,
        "IsPaidPreparer": true
      }
    },
    "AZ": null,
    "IN": {
      "FormWH3": {
        "INWithHoldingID": "4657385932 254",
        "NumOfW2WH18W2G1099Forms": 23,
        "StateTaxWHW2WH18W2G1099": 100,
        "CountyTaxWHW2WH18W2G1099": 100,
        "TotTaxWH": 200,
        "TotDeposits": 500,
        "BalDue": 0,
        "Overpayment": 300,
        "TotCountyTaxWH": 100,
        "CountyTaxWH": [
          {
            "CountyNm": "ADAMS",
            "TaxWH": 50
          },
          {
            "CountyNm": "DECATUR",
            "TaxWH": 50
          }
        ]
      }
    }
  }
},
"Errors": null
}

# GetPDF

TaxBandits provides PDF copies of the tax Return using this API Endpoint. The PDFs can be used for any additional review and approval from your business’ side and it can be distributed to the Employees before the SSA accepts them.

GET FormW2/GetPDF

Request Body

Field	Type	Description
SubmissionId	Guid	Unique identifier of a submission
RecordIds	Guid[]	`Optional` Unique identifier of a records.
TINMaskType	string	`Optional` Choose the masking type of your Employee's SSN on the W-2 PDF. MASKED - The Employee's SSN will be masked in the PDF. Only last 4 digits of the SSN can be read. UNMASKED - The Employee's SSN will not be masked in the PDF. To protect the PII information of the Employee, the PDF with Unmasked SSN is password protected. Use the Employee's SSN (password) to open the protected file. BOTH - Two PDF's will be delivered for each Employee. One with Masked SSN and the other with Unmasked SSN. The PDF with Unmasked SSN will be password protected. Allowed values: "MASKED", "UNMASKED", "BOTH"

Response Body

Field	Type	Description
StatusCode	number	Returns the HTTP status codes like 200,300 etc.
StatusName	string	Name of the status code
StatusMessage	string	Detailed status message
FormW2Records	object[]	Collection of Form W-2 records for which the PDF will be successfully delivered
RecordId	guid	Unique identifier of a record
SequenceId	string	An 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
Message	string	Provides additional information regarding the PDF delivery.
Errors	object[]	Shows detailed error information
Id	string	Returns the validation error id
Name	string	Name of the validation error
Message	string	Description of the validation error

Request JSON

FormW2/GetPDF?SubmissionId=000e9b21-c0fd-421c-867e-93ef54d37b33&RecordIds=f03875e4-e6b5-4cf4-828e-8ca026f0e5e0&TINMaskType=UNMASKED

Response JSON

{
 "StatusCode": 200,
 "StatusName": "Ok",
 "StatusMessage": "Successful API call",
 "SubmissionId": "000e9b21-c0fd-421c-867e-93ef54d37b33",
 "FormW2Records": [
   {
     "RecordId": "f03875e4-e6b5-4cf4-828e-8ca026f0e5e0",
     "SequenceId": "001",
     "Message": "We've successfully received your request to generate PDF. You will be notified with the URL to download the PDF."
   }
 ],
 "Errors": null
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# List

LIST endpoint lets you list the basic details of all the returns irrespective of their record status. List can be customized by sending values corresponding to its optional parameters, which gets applied as filters to the list.

GET FormW2/List

Request Body

Field	Type	Description
SubmissionId	Guid	Unique identifier of a submission
BusinessId	Guid	Unique identifier of a business
EIN	string	Employer Identification Number
TaxYear	string	List the W2 records based on the given taxyear.
Page	number	Pulls the records listed in the page selected
PageSize	number	Number of W-2 records to be listed in each page
EfileStatus	string	List the W-2 records based on the status ("CREATED, UNDERPROCESS, SENTTOAGENCY, TRANSMITTED, ACCEPTED, REJECTED")
FromDate	string	List W-2 records created from
ToDate	string	List W-2 records created up to

Response Body

Field	Type	Description
StatusCode	number	Returns the HTTP status codes like 200,300 etc.
StatusName	string	Name of the status code.
StatusMessage	string	Detailed status message.
FormW2Records	object[]	Returns detailed information of the Form W-2 records
SubmissionId	guid	Unique identifier of a submission
BusinessId	guid	Unique identifier of a business
PayerRef	string	Unique identifier of a payer.
BusinessNm	string	Name of the business
EINorSSN	string	Employer Identification Number or Social Security Number
ContactName	string	Name of the person who can be contacted by the IRS.
TaxYear	string	Tax year of W-2s to be filed.
Employee	object	Returns the employee details.
SequenceId	string	An 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.
RecordId	Guid	An unique identifier generated by TaxBandits when a W2 return is created.
EmployeeId	Guid	An unique identifier generated by TaxBandits for a employee when a W2 return is created. You can use this id for your future reference to Update.
EmployeeName	Boolean	Name of the employee.
SSN	string	SSN of the employee.
Status	string	The status of Form W2.
TotalRecords	number	Total number of records listed in the response.
TotalPages	number	Total number of pages
Page	number	Returns the page number in which the records are listed
PageSize	number	Number of records listed in each page.
Errors	object[]	Shows detailed error information
Id	string	Returns the validation error Id
Name	string	Name of the validation error
Message	string	Description of the validation error

Request JSON

Formw2/List?SubmissionId=08a8d549-2d78-4feb-b18d-f4aded533ab3&BusinessId=5607b044-6809-4399-9645-d20d761b5dcb&EIN=441111211&TaxYear=2021&Page=1&PageSize=10&EfileStatus=ALL&FromDate=11-01-2021&ToDate=11-30-2021

Response JSON

{
   "StatusCode": 200,
   "StatusName": "Ok",
   "StatusMessage": "Successful API call",
   "FormW2Records": [
       {
           "SubmissionId": "08a8d549-2d78-4feb-b18d-f4aded533ab3",
           "BusinessId": "5607b044-6809-4399-9645-d20d761b5dcb",
           "PayerRef": "Pe123",
           "BusinessNm": "Brian LLC",
           "EIN": "44-1111211",
           "ContactName": "Brian O Relly",
           "TaxYear": "2021",
           "Employee": {
               "SequenceId": "001",
               "RecordId": "ae53c621-ea01-4cb5-9e4e-a96987a4eeb1",
               "EmployeeId": "8957652a-7877-4db8-80a5-b555e44c7354",
               "EmployeeName": "Michael John Augustin",
               "SSN": "112-23-6003",
               "Status": "CREATED"
           }
       }
   ],
   "TotalRecords": 1,
   "TotalPages": 1,
   "Page": 1,
   "PageSize": 100,
   "Errors": null
}

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

# StateFiling

One of the important components in tax filing is filing the Forms directly with the State. Most of the states require W-2 to be filed with them directly.

The filing requirements will vary for each state and there is a Reconciliation form filing requirement for most of the states.

Key Points

TaxBandits supports direct state filing for all the states that require state filing.
Some of the states just require Form W-2 filing and no Recon form needs to be filed.
Some of the states require Recon form filing along with the Form W-2s.
- TaxBandits files Recon form on the Employer’s behalf if the state accepts e-filing of Recon Form.
- If the state supports only paper filing of Recon Form, then TaxBandits will not file the Recon Form. It is the Employer’s responsibility to paper file the Form. TaxBandits will provide information on the recon form that needs to be filed in the response.
Some of the states require State specific additional information of the Employee. Those fields are available under the EmployeeStateSpecificData object for specific states.
Only one recon form is required to be filed with the state for the Tax Year and Employer. Make sure you provide the recon information for the state in the first Create request. Once the recon is received for the Tax Year and Employer, our system will not check for mandatory requirements of the recon form in future submissions.
The state filing requirement is separate from Federal filing. You will be notified with a separate webhook response when a state accepts or rejects a W-2 return.

Sl.No	State	DueDate	ReconForm	TaxBandits Responsibilities	Your Responsibilities
1	Alabama	January_31	Form A-3 (opens new window)	TaxBandits will file Form W-2s with the state. TaxBandits will file Recon Form A-3 with the state. Provide the recon information for the state under the StateReconData object.	N/A
2	Alaska	None	None	State does not require direct state filing.	State does not require direct state filing.
3	Arizona	January_31	Form A1-R (opens new window)	TaxBandits will file Form W-2s with the state. TaxBandits will file Recon Form A1-R with the state. Provide the recon information for the state under the StateReconData object.	N/A
4	Arkansas	February_28	Form AR3MAR	TaxBandits will file Form W-2s with the state.	You should take care of filing Form AR3MAR with the state.
5	California	None	None	State does not require direct state filing.	Form W-2 Not required to be filed with the state
6	Colorado	January_31	Form DR-1093	TaxBandits will file Form W-2s with the state.	You should take care of filing Form DR-1093 with the state.
7	Connecticut	January_31	Form CT-W3	TaxBandits will file Form W-2s with the state. TaxBandits will file Recon Form CT-W3 with the state. Provide the recon information for the state under the StateReconData object.	N/A
8	Delaware	January_31	Form W-3	TaxBandits will file Form W-2s with the state.	State Recon Form W-2 is not required when Form W-2 is filed electronically.
9	District of Columbia	January_31	Form WT	TaxBandits will file Form W-2s with the state.	State Recon Form WT is not required when Form W-2 is filed electronically.
10	Florida	None	None	State does not require direct state filing.	State does not require direct state filing.
11	Georgia	January_31	Form G-1003	TaxBandits will file Form W-2s with the state. TaxBandits will file Recon Form G-1003 with the state. Provide the recon information for the state under the StateReconData object.	N/A
12	Hawaii	February_28	Form HW-3	TaxBandits will file Form W-2s with the state.	State Recon Form HW-3 is not required when Form W-2 is filed electronically.
13	Idaho	January_31	Form 967	TaxBandits will file Form W-2s with the state. TaxBandits will file Recon Form 967 with the state. Provide the recon information for the state under the StateReconData object.	N/A
14	Illinois	January_31	none	TaxBandits will file Form W-2s with the state.	State does not require a reconciliation form.
15	Indiana	January_31	Form WH-3	TaxBandits will file Form W-2s with the state. TaxBandits will file Recon Form WH-3 with the state. Provide the recon information for the state under the StateReconData object. Provide the recon information for the state under the StateReconData object. Provide County name for each employee under EmployeeSpecificData object.	N/A
16	Iowa	February_15	Form 44-007 VSP	TaxBandits will file Form W-2s with the state. TaxBandits will file Recon Form 44-007 VSP with the state. Provide the recon information for the state under the StateReconData object.	N/A
17	Kansas	January_31	Form KW-3	TaxBandits will file Form W-2s with the state. TaxBandits will file Recon Form KW-3 with the state. Provide the recon information for the state under the StateReconData object. Provide the recon information for the state under the StateReconData object. Provide Employee Contribution amount for each employee under EmployeeSpecificData object..	N/A
18	Kentucky	January_31	Form K-5	TaxBandits will file Form W-2s with the state.	State Recon Form K-5 is not required when Form W-2 is filed electronically.
19	Louisiana	January_31	Form L-3	TaxBandits will file Form W-2s with the state. TaxBandits will file Recon Form L-3 with the state. Provide the recon information for the state under the StateReconData object.	N/A
20	Maine	February_28	Form W-3ME	TaxBandits will file Form W-2s with the state. TaxBandits will file Recon Form W3-ME with the state. Provide the recon information for the state under the StateReconData object. Provide the recon information for the state under the StateReconData object. Provide MEPERS amount for each employee under EmployeeSpecificData object.	N/A
21	Maryland	January_31	Form MW508	TaxBandits will file Form W-2s with the state. TaxBandits will file Recon Form MW508 with the state. Provide the recon information for the state under the StateReconData object. Provide the recon information for the state under the StateReconData object. Provide Employee Withholding Allowance amount for each employee under EmployeeSpecificData object.	You should take care of filing Form MW508CR, with the state of Maryland if you are claiming tax-exempt credits.
22	Massachusetts	January_31	Form M-3	TaxBandits will file Form W-2s with the state. TaxBandits will file Recon Form M-3 with the state. Provide the recon information for the state under the StateReconData object. Provide the recon information for the state under the StateReconData object. Provide MAPFML amount for each employee under EmployeeSpecificData object.	N/A
23	Michigan	February_28	Form-5081	TaxBandits will file Form W-2s with the state.	You should take care of filing Form 5081 with the state.
24	Minnesota	January_31	none	TaxBandits will file Form W-2s with the state.	State does not require a reconciliation form.
25	Mississippi	January_31	Form 89-140	TaxBandits will file Form W-2s with the state.	State Recon Form 89-140 is not required when Form W-2 is filed electronically.
26	Missouri	January_31	Form MO-W3	TaxBandits will file Form W-2s with the state. TaxBandits will file Recon Form MO-W3 with the state. Provide the recon information for the state under the StateReconData object.	N/A
27	Montana	January_31	Form MW-3	TaxBandits will file Form W-2s with the state. TaxBandits will file Recon Form MW-3 with the state. Provide the recon information for the state under the StateReconData object.	N/A
28	Nebraska	January_31	Form W-3N	TaxBandits will file Form W-2s with the state. TaxBandits will file Recon Form W-3N with the state. Provide the recon information for the state under the StateReconData object.	N/A
29	Nevada	None	None	State does not require direct state filing.	State does not require direct state filing.
30	New Hampshire	None	None	State does not require direct state filing.	State does not require direct state filing.
31	New Jersey	February_15	Form NJ-W-3M	TaxBandits will file Form W-2s with the state. TaxBandits will file Recon Form NJ-W-3M with the state. Provide the recon information for the state under the StateReconData object. Provide the recon information for the state under the StateReconData object. Provide Insurance and Deferred Compensation amounts for each employee under EmployeeSpecificData object.	N/A
32	New Mexico	March_02	Form RPD-41072	TaxBandits will file Form W-2s with the state.	State does not require a reconciliation form.
33	New York	None	None	State does not require direct state filing.	State does not require direct state filing.
34	North Carolina	January_31	Form NC-3	TaxBandits will file Form W-2s with the state. TaxBandits will file Recon Form NC-3 with the state. Provide the recon information for the state under the StateReconData object.	N/A
35	North Dakota	January_31	Form 307	TaxBandits will file Form W-2s with the state.	State does not require a reconciliation form.
36	Ohio	January_31	Form IT-3	TaxBandits will file Form W-2s with the state. TaxBandits will file Recon Form IT-3 with the state. Provide the recon information for the state under the StateReconData object. Provide the recon information for the state under the StateReconData object. Provide School District Number amount for each employee under EmployeeSpecificData object.	N/A
37	Oklahoma	January_31	Form W-3	TaxBandits will file Form W-2s with the state.	State does not require a reconciliation form.
38	Oregon	January_31	Form OR-WR	TaxBandits will file Form W-2s with the state. Provide Employment and Statewide Transit Tax details for each employee under EmployeeSpecificData object..	You should take care of filing Form OR-WR with the state.
39	Pennsylvania	January_31	Form REV-1667	TaxBandits will file Form W-2s with the state. TaxBandits will file Recon Form REV-1667 with the state. Provide the recon information for the state under the StateReconData object.	N/A
40	Rhode Island	January_31	Form RI-W3	TaxBandits will file Form W-2s with the state.	You should take care of filing Form RI-W3 with the state.
41	South Carolina	January_31	Form WH-1606	TaxBandits will file Form W-2s with the state.	You should take care of filing Form WH-1606 with the state.
42	South Dakota	None	None	State does not require direct state filing.	State does not require direct state filing.
43	Tennessee	None	None	State does not require direct state filing.	State does not require direct state filing.
44	Texas	None	None	State does not require direct state filing.	State does not require direct state filing.
45	Utah	January_31	Form TC-941E	TaxBandits will file Form W-2s with the state. TaxBandits will file Recon Form TC-941E with the state. Provide the recon information for the state under the StateReconData object.	N/A
46	Vermont	January_31	Form WHT-434	TaxBandits will file Form W-2s with the state. TaxBandits will file Recon Form WHT-434 with the state. Provide the recon information for the state under the StateReconData object.	N/A
47	Virginia	January_31	Form VA-6/VA-6H	TaxBandits will file Form W-2s with the state. TaxBandits will file Recon Form VA-6 with the state if there is no balance due. Provide the recon information for the state under the StateReconData object.	You should take care of filing Form WH-1606 with the state if you have a balance due.
48	Washington	None	None	State does not require direct state filing.	State does not require direct state filing.
49	West Virginia	January_31	Form WV/IT-103	TaxBandits will file Form W-2s with the state. TaxBandits will file Recon Form WV/IT-103 with the state. Provide the recon information for the state under the StateReconData object.	N/A
50	Wisconsin	January_31	Form WT-7	TaxBandits will file Form W-2s with the state.	You should take care of filing Form WT-7 with the state.
51	Wyoming	None	None	State does not require direct state filing.	State does not require direct state filing.

# RequestDraftPdfUrl

This API request will return the Draft PDF of the forms that are not transmitted yet for review purpose. The draft PDF will have copy A of the form with For Review Only watermark text.

Note: You can only retrieve PDF of a single record/form using this method.

How does it works?

Call the [POST] FormW2/RequestDraftPdfUrl endpoint. You will need to supply the following parameters:
- Access Token in the header as Bearer Token (Generated using TaxBandits OAuth authentication API)
- Request Parameters: Specify the RecordId for the form you need the Draft PDF form. If you do not have the RecordId, then you request the PDF using the following parameters
  - Business Reference - Use the business reference PayerRef or BusinessId or EIN.
  - Employee Reference - Use the recipient reference EmployeeId or SSN.
  - Tax Year - Tax year of the form you are requesting the PDF.

POST FormW2/RequestDraftPdfUrl

Request Body

Field	Type	Description
RecordId	Guid	`Optional` Specify the RecordId of the return
TINMaskType	string	`Optional` TIN Mask type on the TIN printed on the PDF Allowed values: "MASKED", "UNMASKED"
TaxYear	string	`Optional` Tax Year of the return. Specify only if you do not have the RecordId
Business	object	`Optional` Collects the Business identifier TIN or TBS Business Id or PayerRef. This object information is required only if you do not have the RecordId
BusinessId	Guid	`Optional` TaxBandits Unique Business Identifier. This ID is generated by TaxBandits after you create a business in your account using the Business endpoint.
PayerRef	string	`Optional` Unique payer identifier assigned by the client. Size Range: 1 to 50
EIN	string	`Optional` Employer Identification Number. Use this as an alternative for BusinessId or PayerRef. Size Range: 9 to 10
Employee	object	`Optional` Collects the employee's unique identifier. This object information is required only if you do not have the RecordId
EmployeeId	Guid	`Optional` Unique Employee Identifier generated by TaxBandits
SSN	string	`Optional` Social Security Number. Use this as an alternative for EmployeeIds. Size Range: 9 to 11

Response Body

Field	Type	Description
RecordId	Guid	Unique identifier of the record
EmployeeId	Guid	Unique Employee Identifier generated by TaxBandits
DraftPdfUrl	string	URL of the Draft PDF
Errors	object[]	Shows detailed error information
Id	string	Returns the validation error code
Name	string	Name of the validation error
Message	string	Description of the validation error

Request JSON 1: With just the RecordId

{
 "TaxYear": null,
 "RecordId": "cf0a188b-6661-4b57-b04b-ba9ead52a16e",
 "TINMaskType":"Masked",
 "Business": null,
 "Employee": null
}

1
2
3
4
5
6
7

Response JSON 1

{
   "RecordId": "cf0a188b-6661-4b57-b04b-ba9ead52a16e",
   "EmployeeId": "bd2221f7-4be6-4cc7-813c-6346e23b9f63",
   "DraftPdfUrl": "https://expressirsforms.s3.us-east-1.amazonaws.com/pdfs/a570efbd-740f-4ae2-bfe7-26356cd85148/3e99f728-e9d4-4d88-99b6-e00638da7a5b/W-2/221556/dcopy_tbs_wm_1up_221556.pdf",
   "Error": null
}

1
2
3
4
5
6

Request JSON 2: With No RecordId

{
 "TaxYear": "2021",
 "RecordId": null,
 "TINMaskType":"Unmasked",
 "Business": {
   "BusinessId": "94B6214D-8DCA-490C-8FC3-602840B439B5",
   "PayerRef": null,
   "EIN": null
 },
 "Employee": {
   "EmployeeId": "6DDFFB5A-565F-402D-8602-7ECD917CEC04",
   "SSN": null
 }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14

Response JSON 2

{
   "RecordId": "cf0a188b-6661-4b57-b04b-ba9ead52a16e",
   "EmployeeId": "bd2221f7-4be6-4cc7-813c-6346e23b9f63",
   "DraftPdfUrl": "https://expressirsforms.s3.us-east-1.amazonaws.com/pdfs/a570efbd-740f-4ae2-bfe7-26356cd85148/3e99f728-e9d4-4d88-99b6-e00638da7a5b/W-2/221556/d/copy_tbs_wm_1up_221556.pdf",
   "Error": null
}

1
2
3
4
5
6

# RequestPdfURLs

This method can be used to retrieve PDFs for single or multiple recipients. The PDF URL will be returned in the response only if it is already generated by us. You can use the SubmissionId or RecordIds to request the pdf URLs.

Note: The PDF URL will be returned in response only after the return is transmitted in the API. This method will not work for Inprogress returns.

POST FormW2/RequestPdfURLs

Request Body

Field	Type	Description
SubmissionId	Guid	`Optional` Unique identifier of an API submission. Use this node to request the PDFs under a particular submission. If you are going to request the PDFs using the RecordIds, you can leave the SubmissionId blank or null.
RecordIds	object[]	Contains the list of RecordIds for which you are requesting the pdf URLs
RecordId	Guid	Unique identifier of the return.
Customization	object	Contains PDF customizations
TINMaskType	string	`Optional` Mention whether you want the TIN to be masked in the PDF. If masked, only the last digits of the SSN will be visible and the rest of the digits will be crossed (xxx-xx-1234). Allowed values: "MASKED", "UNMASKED", "BOTH"

Response Body

Field	Type	Description
SubmissionId	Guid	Unique identifier of a submission.
FormW2Records	object	Contains success and error records of the requested RecordIds.
SuccessRecords	object[]	Contains the successful records with pdf urls if the forms are generated.
RecordId	Guid	Unique identifier of the return.
Status	string	Status of the PDF in TaxBandits. Success - The PDF is generated and you can download it.
Files	object	Contains multiple copies of a particular return.
Copy1	object	Copy 1: For State, City, or Local Tax Department
Unmasked	string	Link to download the Unmasked copy
Masked	string	Link to download the Masked copy
Copy2	object	Copy 2: To Be Filed With Employee’s State, City, or Local Income Tax Return
Unmasked	string	Link to download the Unmasked copy
Masked	string	Link to download the Masked copy
CopyB	object	Copy B: To Be Filed With Employee’s FEDERAL Tax Return.
Unmasked	string	Link to download the Unmasked copy
Masked	string	Link to download the Masked copy
CopyC	object	Copy C: For EMPLOYEE’S RECORDS
Unmasked	string	Link to download the Unmasked copy
Masked	string	Link to download the Masked copy
CopyD	object	Copy D: For Employer
Unmasked	string	Link to download the Unmasked copy
Masked	string	Link to download the Masked copy
ErrorRecords	object[]	Contains the error records
RecordId	Guid	Unique identifier of the return.
Status	string	Status of the error record. PDF_Not_Generated - PDF is yet to be generated. You will have to wait and send a new API request to get the PDF. Not Transmitted - The return is not transmitted yet. Invalid RecordId - Given record id is invalid
Message	string	Description of each statuses
Errors	object[]	Lists the errors in the API call
Id	string	Returns the error Id.
Name	string	Name of the validation error
Message	string	Description of the validation error

Sample Request JSON 1

{
  "SubmissionId": "03f83fe9-05ca-41f0-86c3-00d073528712",
  "RecordIds": [
    {
      "RecordId": "2388983e-0215-4c99-8033-951dee1ccfef"
    }
  ],
  "Customization": {
    "TINMaskType": "Masked"
  }
}

1
2
3
4
5
6
7
8
9
10
11

Sample Response JSON 1

{
   "SubmissionId": "03f83fe9-05ca-41f0-86c3-00d073528712",
   "FormW2Records": {
       "SuccessRecords": [
           {
               "RecordId": "2388983e-0215-4c99-8033-951dee1ccfef",
               "Status": "Success",
               "Files": {
                   "Copy1": {
                       "Unmasked": null,
                       "Masked": "https://expressirsforms.s3.us-east-1.amazonaws.com/pdfs/769e7c15-b887-4d64-a50f-444ab16f50d0/d59cd157-4a07-4832-9390-2704a65de1b8/w2/7d42c237-01ae-442f-b669-69ac174f50ab/m/copy1_1up_5989647027.pdf"
                   },
                   "Copy2": {
                       "Unmasked": null,
                       "Masked": "https://expressirsforms.s3.us-east-1.amazonaws.com/pdfs/769e7c15-b887-4d64-a50f-444ab16f50d0/d59cd157-4a07-4832-9390-2704a65de1b8/w2/7d42c237-01ae-442f-b669-69ac174f50ab/m/copy2_1up_9886910187.pdf"
                   },
                   "CopyB": {
                       "Unmasked": null,
                       "Masked": "https://expressirsforms.s3.us-east-1.amazonaws.com/pdfs/769e7c15-b887-4d64-a50f-444ab16f50d0/d59cd157-4a07-4832-9390-2704a65de1b8/w2/7d42c237-01ae-442f-b669-69ac174f50ab/m/copyb_1up_8292618360.pdf"
                   },
                   "CopyC": {
                       "Unmasked": null,
                       "Masked": "https://expressirsforms.s3.us-east-1.amazonaws.com/pdfs/769e7c15-b887-4d64-a50f-444ab16f50d0/d59cd157-4a07-4832-9390-2704a65de1b8/w2/7d42c237-01ae-442f-b669-69ac174f50ab/m/copyc_1up_2897463954.pdf"
                   },
                   "CopyD": {
                       "Unmasked": null,
                       "Masked": "https://expressirsforms.s3.us-east-1.amazonaws.com/pdfs/769e7c15-b887-4d64-a50f-444ab16f50d0/d59cd157-4a07-4832-9390-2704a65de1b8/w2/7d42c237-01ae-442f-b669-69ac174f50ab/m/copyd_1up_4876050156.pdf"
                   }
               }
           }
       ],
       "ErrorRecords": null
   },
   "Errors": null
}

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

Sample Request JSON 2

{
 "SubmissionId": "a863c015-91f1-4128-84fc-bb38922b80f9",
 "RecordIds": [
   {
     "RecordId": "c4446e74-ee11-43e4-b9db-a7e870714267"
   },
   {
     "RecordId": "f11413f7-3fe3-4d55-9e87-66b687bc404e"
   }
 ],
 "Customization": {
   "TINMaskType": "Masked"
 }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14

Sample Response JSON 2

{
   "SubmissionId": null,
   "FormW2Records": {
       "SuccessRecords": null,
       "ErrorRecords": [
           {
               "RecordId": "c4446e74-ee11-43e4-b9db-a7e870714267",
               "Status": "PDF_Not_Generated",
               "Message": "Your PDF request is prioritized in the queue.Please try again after sometime"
           },
           {
               "RecordId": "f11413f7-3fe3-4d55-9e87-66b687bc404e",
               "Status": "Not Transmitted",
               "Message": "Given RecordId is not transmitted"
           }
       ]
   },
   "Errors": null
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

Sample Request JSON 3

{
   "RecordIds": [
   {
     "RecordId": "c4446e74-ee11-43e4-b9db-a7e870714267"
   },
   {
     "RecordId": "f11413f7-3fe3-4d55-9e87-66b687bc404e"
   }
 ]

}

1
2
3
4
5
6
7
8
9
10
11

Sample Response JSON 3

{
   "SubmissionId": null,
   "FormW2Records": {
       "SuccessRecords": null,
       "ErrorRecords": [
           {
               "RecordId": "c4446e74-ee11-43e4-b9db-a7e870714267",
               "Status": "PDF_Not_Generated",
               "Message": "Your PDF request is prioritized in the queue.Please try again after sometime"
           },
           {
               "RecordId": "f11413f7-3fe3-4d55-9e87-66b687bc404e",
               "Status": "Not Transmitted",
               "Message": "Given RecordId is not transmitted"
           }
       ]
   },
   "Errors": null
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# Status

This method will return the current status of the Form W-2 for a particular submission or for a particular employee.

Federal Return Statuses:

Created: Form W-2 has been created and not yet transmitted by the user.
Transmitted: Form W-2 has been transmitted by the user.
Order Received: Form W-2 order is received and waiting in our efile queue.7
Under Process: Our efile system is processing the Form W-2 which will be sent to the SSA soon.
Sent to Agency: Form W-2 has been sent to the SSA and we are waiting for the result from SSA.
Accepted: Form W-2 is accepted by the SSA.
Rejected: Form W-2 is rejected by the SSA due to some errors. Please correct the errors and retransmit them.

State Return Statuses:

Not Created: State filing is not opted for the return. IsStateFiling in the submission manifest must be set as TRUE to enable state filing.
Created: Form W-2 state return has been created and not yet transmitted by the user.
Transmitted: Form W-2 state return has been transmitted by the user.
Order Received: State order is received and waiting in our efile queue.
Under Process: Our efile system is processing the Form W-2 for the state which will be sent to the state DOR soon.
Sent to Agency: Form W-2 State return has been sent to the DOR and we are waiting for the result.
Accepted: Form W-2 state return is accepted by the DOR.
Rejected: Form W-2 state return is rejected by the DOR due to some errors. Please correct the errors and retransmit them.

Postal Mailing Statuses:

Not Created: Postal Mailing is not opted for the return. IsPostalMailing in the submission manifest must be set as TRUE to enable postal mailing. Postal Mailing cannot be created for employees with Foreign addresses.
Created: Postal Mailing service is opted for the return and it will be sent as soon as the form is transmitted.
Order Received: Postal Mailing order has been received and the mails will be sent out soon.
Order Sent: Postal Mailing order has been sent and the employee will receive the copy soon.

Online Access Statuses:

Not Created: Online Access service is not opted for the return. IsOnlineAccess in the submission manifest must be set as TRUE to enable Online Access. Email Address is required to create Online Access.
Created: Online Access service is opted for the return and the email with a secure link to download their forms will be sent to the employees as soon as the form is transmitted.
Order Received: Online Access order has been received and the email will be sent to the employee soon.
Email Sent: Online Access email with a secure link to download the form has been sent to the employee and the employee is yet to view the form.
Viewed Form: Employee has successfully viewed the form.
Downloaded Form: Employee has successfully viewed and downloaded the form.

GET FormW2/Status

Request Body

Field	Type	Description
SubmissionId	guid	Unique identifier of a submission
RecordIds	Guid[]	Number of record Ids to get status.

Response Body

Field	Type	Description
StatusCode	number	Returns the HTTP status codes like 200,300 etc.
StatusName	string	Name of the status code
StatusMessage	string	Detailed status message
SubmissionId	Guid	Unique identifier of a submission
BusinessId	Guid	Unique identifier of a Business.
PayerRef	string	Unique identifier of a Payer.
FormW2Records	object	Pulls the Form W-2 records with Success and Error statuses
SuccessRecords	object[]	It will show the detailed information about the success status of Form W2 Records
SequenceId	string	An 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.
RecordId	Guid	An unique identifier generated by TaxBandits when a W2 return is created.
EmployeeId	Guid	An unique identifier generated by TaxBandits for a employee when a W2 return is created. You can use this id for your future reference to Update.
FederalReturn	object	Returns the record status and StatusTs of federal return.
Status	string	Returns the record status.
StatusTs	string	Returns date and time of return created.
Info	string	Returns information about the Federal Filing service.
StateReturns	object[]	Returns collection of state returns information
StateCd	string	Returns the state code of the state for which the return is filed.
Status	string	Returns the record status of the state return.
StatusTs	string	Date and time of the return created.
Info	string	Returns the information about the state for which we are not supporting state filing.
Errors	object[]	Shows error information of state returns of Form W2
Id	string	Returns the validation error Id.
Name	string	Name of the validation error.
Message	string	Description of the validation error.
Postal	object	Returns the status and StatusTs of postal mailing service for Form W2.
Status	string	Returns the status of postal order.
StatusTs	string	Returns the date and time of the postal order created.
Info	string	Returns the information about Postal mailing service.
OnlineAccess	object	Returns the Email address for whom the online access to be given and Status of online access.
Status	string	Returns the Status of the Online Access.
Email	string	Email address for whom the online access to be given.
Info	string	Information about the online access service.
ScheduleFiling	object	Returns the date of the schedule filing.
ScheduledOn	string	Date of the schedule filing to know when the return to be filed to the IRS.
Info	string	Information about Schedule Filing service.
ErrorRecords	object[]	It will show the detailed information about the error status of Form W2 Records.
SequenceId	string	An 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.
RecordId	Guid	Unique identifier of a record
Errors	object[]	Shows detailed error information
Id	string	Returns the validation error Id
Name	string	Name of the validation error
Message	string	Description of the validation error
Errors	object[]	Shows detailed error information
Id	string	Returns the validation error Id
Name	string	Name of the validation error
Message	string	Description of the validation error

Request JSON

FormW2/Status?SubmissionId=d1f9cb0a-912f-4105-8bcf-059af43d2b31&RecordIds=63842ea1-93ac-4e5f-a3b2-df59c2d147c5

Response JSON

{
  "StatusCode": 200,
  "StatusName": "Ok",
  "StatusMessage": "Successful API call",
  "SubmissionId": "d1f9cb0a-912f-4105-8bcf-059af43d2b31",
  "BusinessId": "62ac9c76-4fa8-4459-8a7d-e9763862d5fa",
  "PayerRef": "Pe123",
  "FormW2Records": {
      "SuccessRecords": [
          {
              "SequenceId": "001",
              "RecordId": "63842ea1-93ac-4e5f-a3b2-df59c2d147c5",
              "EmployeeId": "ad035610-bfc0-494b-a3f0-5eeaf51408ec",
              "FederalReturn": {
                  "Status": "CREATED",
                  "StatusTs": "2021-11-20 15:02:51 +05:30",
                  "Info": null
              },
              "StateReturns": [
                      {
                        "StateCd": "IN",
                        "Status": "State Filing Order Received",
                        "StatusTs": "2021-08-06 10:32:40 -04:00",
                        "Info": null,
                        "Errors": null
                      },
                      {
                        "StateCd": "VT",
                        "Status": "State Filing Order Received",
                        "StatusTs": "2021-08-06 10:32:40 -04:00",
                        "Info": null,
                        "Errors": null
                      },
                      {
                        "StateCd": "PA",
                        "Status": "State Filing Order Received",
                        "StatusTs": "2021-08-06 10:32:40 -04:00",
                        "Info": null,
                        "Errors": null
                      },
                      {
                        "StateCd": "KS",
                        "Status": "State Filing Order Received",
                        "StatusTs": "2021-08-06 10:32:40 -04:00",
                        "Info": null,
                        "Errors": null
                      }
                 ],
              "Postal": {
                  "Status": "NOTCREATED",
                  "StatusTs": null,
                  "Info": "Postal Alert cannot be opted for the return, when the employee (or) business has foreign address"
              },
              "OnlineAccess": {
                  "Status": "CREATED",
                  "Email": "john@gmail.com",
                  "Info": null
              },
              "ScheduleFiling": null
          }
      ],
      "ErrorRecords": null
  },
  "Errors": null
}

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

# Transmit

Transmit API Endpoint is used to “E-File” the Tax return with the SSA/State Agencies. This endpoint applies the same data validation checks and business rules as CREATE and VALIDATE endpoints. This endpoint can not be called without calling the CREATE endpoint as this endpoint will not create the Tax Return. Once “Transmitted”, based on the options selected, the tax return will be E-Filed with the Federal and/or state agencies and also will be postal mailed to the employees.

POST FormW2/Transmit

Request Body

Field	Type	Description
SubmissionId	Guid	Unique identifier of a submission
RecordIds	Guid[]	An unique identifier generated by TaxBandits when a W2 return is created. Mention the W2 return's Record ID that you want to transmit.

Response Body

Field	Type	Description
StatusCode	number	Returns the HTTP status codes like 200,300 etc.
StatusName	string	Name of the status code
StatusMessage	string	Detailed status message
SubmissionId	Guid	Unique identifier of a submission
FormW2Records	object	Pulls the Form W-2 records with Success and Error statuses
SuccessRecords	object[]	It will show the detailed information about the success status of Form W2 Records
SequenceId	string	An 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.
RecordId	Guid	Unique identifier of a record
Status	string	Returns the status of the records.
StatusTs	string	Date and time of return created.
StateReturns	object[]	Returns the state code and return status.
StateCode	string	Returns the code of the state.
RecordStatus	string	Returns the status of the records.
ErrorRecords	object[]	It will show the detailed information about the error status of Form W2 Records.
RecordId	Guid	Unique identifier of a record
SequenceId	string	An 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.
RejectedBy	string	Returns the information of who rejected the return.
Errors	object[]	Shows detailed error information
Id	string	Returns the validation error id
Name	string	Name of the validation error
Message	string	Description of the validation error
Errors	object[]	Shows detailed error information
Id	string	Returns the validation error Id
Name	string	Name of the validation error
Message	string	Description of the validation error

Request JSON

{
"SubmissionId": "ef869fda-5562-41c8-b0d2-b61ef19a2f5a",
"RecordIds": [
"566e1623-3c07-4d15-9fcc-00cad9a3a5d5"
 ]
}

1
2
3
4
5
6

Response JSON

{
 "StatusCode": 200,
 "StatusName": "Ok",
 "StatusMessage": "Successful API call",
 "SubmissionId": "ef869fda-5562-41c8-b0d2-b61ef19a2f5a",
 "FormW2Records": {
   "SuccessRecords": [
     {
       "SequenceId": "001",
       "RecordId": "566e1623-3c07-4d15-9fcc-00cad9a3a5d5",
       "Status": "Transmitted",
       "StatusTs": "2021-08-06 10:32:38 -04:00",
       "StateReturns": [
         {
           "StateCode": "IN",
           "RecordStatus": "Transmitted"
         },
         {
           "StateCode": "VT",
           "RecordStatus": "Transmitted"
         },
         {
           "StateCode": "PA",
           "RecordStatus": "Transmitted"
         },
         {
           "StateCode": "KS",
           "RecordStatus": "Transmitted"
         }
       ]
     }
   ],
   "ErrorRecords": null
 },
 "Errors": null
}

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

# Update

Once the Tax Return is created, any changes to the tax return must happen using the UPDATE API Endpoint. To update the Tax Return, the Update Request payload must contain the unique IDs — Submission ID and the Record ID to update the appropriate transaction and the tax return.

PUT FormW2/Update

Request Body

Field	Type	Description
SubmissionManifest	object	SubmissionManifest provides the brief information about a particular submission on the whole. It contains information like Submission ID, Tax Year, IsPostal, IsFederalFiling, IsStateFiling, IsOnlineAccess, IsScheduleFiling & ScheduleFiling service details.
SubmissionId	Guid	Unique identifier created by TaxBandits for each submission. Not required when you are creating a return.
TaxYear	string	Tax year of Form W2 to be filed. Allowed values: "2021"
IsFederalFiling	Boolean	Federal Filing for the return will be enabled when the value is True. Form W2 will be sent directly to the IRS.
IsStateFiling	Boolean	State Filing for the return will be enabled when the value is True. Form W2 will be directly filed with the respective employee states. Note: State Filing will not be created for the states that do not require State filing.
IsPostal	Boolean	Postal Order will be created when the value is set as True. Once the return is Transmitted, Form W2 employee copies will be postal mailed to the employee's address via USPS. Note: Postal Orders for Foreign Address will not be created.
IsOnlineAccess	Boolean	Online Access will be enabled when the value is set as True. Once the return is Transmitted, an email with the link to the secure TaxBandits portal will be sent to the employee. The employee can provide consent and download Form W2 employee copies from the portal.
IsScheduleFiling	Boolean	When true, schedule filing services will be provided for W2 returns under this submission.
ScheduleFiling	object	Contains preferred date to submit the returns to the IRS. 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: 10/20/2021 or 10-20-2021
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), you received in the response of the Business CREATE Endpoint. If you have 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` An unique identifier for each payer completing their information. This identifier can be used in future references of the payer in the API. Size Range: ..75
BusinessNm	string	Name of the business Size Range: ..75
TradeNm	string	`Optional` Name under which the business operates Size Range: ..75
IsEIN	Boolean	When true, identifies the business with an EIN.
EINorSSN	string	Enter the Employer Identification Number (EIN) as you are filing Form W-2. You can not file Form W-2 with your SSN. Size Range: 9
Email	string	Email address of the Business Size Range: ..40
ContactNm	string	`Optional` Name of the person who can be contacted by the IRS Size Range: ..27
Phone	string	Phone number of the business Size Range: 10
PhoneExtn	string	`Optional` Extension of the business phone number Size Range: ..5
Fax	string	`Optional` Fax number of the Business Size Range: 10
BusinessType	string	`Optional` Type of business. Optional for W-2/1099 and mandatory for 94X series Size Range: 4 Allowed values: "ESTE", "PART", "CORP", "EORG", "SPRO"
SigningAuthority	object	`Optional` Details of the person who is authorized to sign the return
Name	string	`Optional` Name of the signing authority Size Range: ..35
Phone	string	`Optional` Phone number of the signing authority Size Range: 10
BusinessMemberType	string	`Optional` Business title of the signing authority Size Range: 5..29 Allowed values: "CORPORATESECRETARY", "SECRETARYTREASURER", "PARTNER", "GENERALPARTNER", "LIMITEDPARTNER", "LLCMEMBER", "MANAGINGMEMBER", "MANAGER", "TAXMATTERPARTNER", "PRESIDENT", "VICEPRESIDENT", "CORPORATETREASURER", "TREASURER", "ASSISTANTTREASURER", "CHIEFACCOUNTINGOFFICER", "CHIEFEXECUTIVEOFFICER", "CHIEFFINANCIALOFFICER", "TAXOFFICER", "CHIEFOPERATINGOFFICER", "CORPORATEOFFICER", "EXECUTIVEDIRECTOR", "DIRECTOR", "CHAIRMAN", "EXECUTIVEADMINISTRATOR", "RECEIVER", "PASTOR", "ASSISTANTTORELIGIOUSLEADER", "REVEREND", "PRIEST", "MINISTER", "RABBI", "LEADEROFRELIGIOUSORGANIZATION", "SECRETARY", "DIRECTOROFTAXATION", "DIRECTOROFPERSONNEL", "ADMINISTRATOR", "EXECUTOR", "TRUSTEE", "FIDUCIARY", "OWNER", "SOLEPROPRIETOR", "MEMBER", "SOLEMEMBER"
KindOfEmployer	string	`Optional` Identifies the kind of employer. Mandatory for W-2 and optional for 1099-MISC and 94X series Allowed values: "FEDERALGOVT", "STATEORLOCAL501C", "NONGOVT501C", "STATEORLOCALNON501C", "NONEAPPLY"
KindOfPayer	string	`Optional` Identifies the kind of payer. This field is mandatory in W-2 and optional in 1099-MISC and 94X series Allowed values: "REGULAR941", "REGULAR944", "AGRICULTURAL943", "HOUSEHOLD", "MILITARY", "MEDICAREQUALGOVEM", "RAILROADFORMCT1"
IsBusinessTerminated	Boolean	When true, identifies the business as terminated.
IsForeign	Boolean	When true, identifies the business address with a foreign address.
USAddress	object	If IsForeign is false, pass US address of the business
Address1	string	Employer/Payer's US address (street address or post office box of that locality) Size Range: ..35
Address2	string	`Optional` Employer/Payer's suite or apartment Size Range: ..35
City	string	Employer/Payer's city Size Range: ..27
State	string	Employer/Payer's state code. Refer Static values. Size Range: 2 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"
ZipCd	string	Employer/Payer's zip code
ForeignAddress	object	If IsForeign is true, pass foreign address of the business
Address1	string	Employer/Payer's foreign address (street address or post office box of that locality) Size Range: ..35
Address2	string	`Optional` Employer/Payer's suite or apartment Size Range: ..35
City	string	Employer/Payer's city Size Range: ..27
ProvinceOrStateNm	string	Employer/Payer's province or state name Size Range: ..30
Country	string	Employer/Payer's country Size Range: 2 Allowed values: "US", "CA", "MX", "AF", "AX", "XI", "AL", "AG", "AQ", "AN", "AO", "AV", "AY", "AC", "AR", "AM", "AA", "XA", "AT", "AS", "AU", "AJ", "XZ", "BF", "BA", "FQ", "BG", "BB", "BS", "BO", "BE", "BH", "BN", "BD", "BT", "BL", "BK", "BC", "BV", "BR", "IO", "VI", "BX", "BU", "UV", "BM", "BY", "CB", "CM", "XY", "CV", "CJ", "CT", "CD", "XC", "CI", "CH", "KT", "IP", "CK", "CO", "CN", "CF", "CG", "CW", "CR", "VP", "CS", "IV", "HR", "CU", "CY", "EZ", "DA", "DX", "DJ", "DO", "DR", "TT", "EC", "EG", "ES", "UK", "EK", "ER", "EN", "ET", "EU", "FK", "FO", "FM", "FJ", "FI", "FR", "FG", "FP", "FS", "GB", "GA", "GZ", "GG", "GM", "GH", "GI", "GO", "GR", "GL", "GJ", "GP", "GQ", "GT", "GK", "GV", "PU", "GY", "HA", "HM", "HO", "HK", "HQ", "HU", "IC", "IN", "ID", "IR", "IZ", "EI", "IS", "IT", "JM", "JN", "JA", "DQ", "JE", "JQ", "JO", "JU", "KZ", "KE", "KQ", "KR", "KN", "KS", "KU", "KG", "LA", "LG", "LE", "LT", "LI", "LY", "LS", "LH", "LU", "MC", "MK", "MA", "MI", "MY", "MV", "ML", "MT", "IM", "RM", "MB", "MR", "MP", "MF", "MQ", "MD", "MN", "MG", "MJ", "MH", "MO", "MZ", "XM", "WA", "NR", "BQ", "NP", "NL", "NT", "NC", "NZ", "NU", "NG", "NI", "NE", "NF", "XN", "CQ", "NO", "MU", "OC", "PK", "LQ", "PS", "PM", "PP", "PF", "PA", "PE", "RP", "PC", "PL", "PO", "RQ", "QA", "RE", "RO", "RS", "RW", "WS", "SM", "TP", "SA", "XS", "SG", "RI", "SE", "SL", "SN", "XR", "LO", "SI", "BP", "SO", "SF", "SX", "SP", "PG", "CE", "SH", "SC", "ST", "SB", "VC", "SU", "NS", "SV", "WZ", "SW", "SZ", "SY", "TW", "TI", "TZ", "TH", "TO", "TL", "TN", "TD", "XT", "TE", "TS", "TU", "TX", "TK", "TV", "UG", "UP", "AE", "UY", "UZ", "NH", "VT", "VE", "VM", "VQ", "WQ", "XW", "WF", "WE", "WI", "YM", "YI", "ZA", "ZI"
PostalCd	string	Employer/Payer's postal code
ReturnData	object[]	Contains information about the employee details and Form W2 details.
SequenceId	string	An 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
RecordId	Guid	Unique Identifier of the Record. Mention the Form W2 return's Record ID that you want to update. If you do not provide the Record ID, then a new record will be added to the submission.
Employee	object	Object to identify the employee details.
EmployeeId	Guid	An unique ID generated by TaxBandits after the return is created and will be returned in the Response. You can use this id for your future reference to Update.
SSN	string	Employee's Social Security Number (SSN) Size Range: 9
FirstNm	string	Employee's first name.
MiddleNm	string	`Optional` Employee's middle name.
LastNm	string	Employee's last name.
Suffix	string	`Optional` Employee's suffix. Allowed values: "Jr", "Sr", "I", "II", "III", "IV", "V", "VI", "VII"
Email	string	`Optional` Employee's email address. Size Range: 0..40
Fax	string	`Optional` Employee's fax number. Size Range: 10
Phone	string	`Optional` Employee's phone number Size Range: 10
IsForeign	Boolean	When true, identifies the employee address with a foreign address.
USAddress	object	Object to identify the employee's US address
Address1	string	Employee's US address (street address or post office box of that locality) Size Range: ..35
Address2	string	Employee's suite or apartment Size Range: ..35
City	string	Employee's city Size Range: ..27
State	string	Employee's State code. Refer Static values. Size Range: 2 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"
ZipCd	string	Employee's zip code
ForeignAddress	object	If IsForeign is true, pass foreign address of the employee
Address1	string	Employee's foreign address (street address or post office box of that locality) Size Range: ..35
Address2	string	`Optional` Employee's suite or apartment Size Range: ..35
City	string	Employee's city. Size Range: ..27
ProvinceOrStateNm	string	Employee's Province or State Name. Size Range: ..30
Country	string	Employee's country code. Refer Static values. Size Range: 2 Allowed values: "US", "CA", "MX", "AF", "AX", "XI", "AL", "AG", "AQ", "AN", "AO", "AV", "AY", "AC", "AR", "AM", "AA", "XA", "AT", "AS", "AU", "AJ", "XZ", "BF", "BA", "FQ", "BG", "BB", "BS", "BO", "BE", "BH", "BN", "BD", "BT", "BL", "BK", "BC", "BV", "BR", "IO", "VI", "BX", "BU", "UV", "BM", "BY", "CB", "CM", "XY", "CV", "CJ", "CT", "CD", "XC", "CI", "CH", "KT", "IP", "CK", "CO", "CN", "CF", "CG", "CW", "CR", "VP", "CS", "IV", "HR", "CU", "CY", "EZ", "DA", "DX", "DJ", "DO", "DR", "TT", "EC", "EG", "ES", "UK", "EK", "ER", "EN", "ET", "EU", "FK", "FO", "FM", "FJ", "FI", "FR", "FG", "FP", "FS", "GB", "GA", "GZ", "GG", "GM", "GH", "GI", "GO", "GR", "GL", "GJ", "GP", "GQ", "GT", "GK", "GV", "PU", "GY", "HA", "HM", "HO", "HK", "HQ", "HU", "IC", "IN", "ID", "IR", "IZ", "EI", "IS", "IT", "JM", "JN", "JA", "DQ", "JE", "JQ", "JO", "JU", "KZ", "KE", "KQ", "KR", "KN", "KS", "KU", "KG", "LA", "LG", "LE", "LT", "LI", "LY", "LS", "LH", "LU", "MC", "MK", "MA", "MI", "MY", "MV", "ML", "MT", "IM", "RM", "MB", "MR", "MP", "MF", "MQ", "MD", "MN", "MG", "MJ", "MH", "MO", "MZ", "XM", "WA", "NR", "BQ", "NP", "NL", "NT", "NC", "NZ", "NU", "NG", "NI", "NE", "NF", "XN", "CQ", "NO", "MU", "OC", "PK", "LQ", "PS", "PM", "PP", "PF", "PA", "PE", "RP", "PC", "PL", "PO", "RQ", "QA", "RE", "RO", "RS", "RW", "WS", "SM", "TP", "SA", "XS", "SG", "RI", "SE", "SL", "SN", "XR", "LO", "SI", "BP", "SO", "SF", "SX", "SP", "PG", "CE", "SH", "SC", "ST", "SB", "VC", "SU", "NS", "SV", "WZ", "SW", "SZ", "SY", "TW", "TI", "TZ", "TH", "TO", "TL", "TN", "TD", "XT", "TE", "TS", "TU", "TX", "TK", "TV", "UG", "UP", "AE", "UY", "UZ", "NH", "VT", "VE", "VM", "VQ", "WQ", "XW", "WF", "WE", "WI", "YM", "YI", "ZA", "ZI"
PostalCd	string	Employee's Postal Code
W2FormData	object	Employee's Form W-2 information
B1Wages	number	Gets the total taxable wages, tips, and other compensation paid by the employer to employees during the year. These figures should be prior to payroll deductions. Size Range: 0-999999999.99
B2FedTaxWH	number	Gets the total federal income tax withheld from the employee's wages for the year. Include the 20% excise tax withheld on excess parachute payments. Size Range: 0-999999999.99
B3SocSecWages	number	Gets the total wages paid (before payroll deductions) subject to employee social security tax. Size Range: 0-999999999.99
B4SocSecTaxWH	number	Gets the total amount of social security tax withheld from employees. Include only taxes withheld for wages and tips. Size Range: 0-999999999.99
B5MediWages	number	Gets the amount of wages and tips subject to medicare tax. These are similar to those subject to social security tax (boxes 3 and 7) except that there is no wage base limit for Medicare tax. Size Range: 0-999999999.99
B6MediTaxWH	number	Gets the amount of taxes withheld from employees for Medicare tax Size Range: 0-999999999.99
B7SocSecTips	number	Gets the tips reported by the employee for which the employer did not have enough employee funds to collect the social security tax for the tips. Size Range: 0-999999999.99
B8AllocatedTips	number	Gets the tips allocated to your employee if you operate a large food or beverage establishment. Size Range: 0-999999999.99
B10DependtCareBenefits	number	Gets the total amount of dependent care benefits paid or incurred by the employer for employees under a dependent care assistance program. Size Range: 0-999999999.99
B11Sec457Plan	number	Gets the amount distributed to an employee from the employer's non-qualified plan Size Range: 0-999999999.99
B11NonSec457Plan	number	Gets the amount distributed to an employee from the employer's non-governmental section 457(b) plan Size Range: 0-999999999.99
B12aAmt	number	Enter the amount value for the code selected under Box 12a. Size Range: 0-999999999.99
B12bAmt	number	Enter the amount value for the code selected under Box 12b. Size Range: 0-999999999.99
B12cAmt	number	Enter the amount value for the code selected under Box 12c. Size Range: 0-999999999.99
B12dAmt	number	Enter the amount value for the code selected under Box 12d. Size Range: 0-999999999.99
B12aCd	string	Enter the Box 12a Code. Allowed values: "A", "B", "C", "D", "E", "F", "G", "H", "J", "K", "L", "M", "N", "P", "Q", "R", "S", "T", "V", "W", "Y", "Z", "AA", "BB", "CC", "DD", "EE", "FF", "GG", "HH"
B12bCd	string	Enter the Box 12b Code. Allowed values: "A", "B", "C", "D", "E", "F", "G", "H", "J", "K", "L", "M", "N", "P", "Q", "R", "S", "T", "V", "W", "Y", "Z", "AA", "BB", "CC", "DD", "EE", "FF", "GG", "HH"
B12cCd	string	Enter the Box 12c Code. Allowed values: "A", "B", "C", "D", "E", "F", "G", "H", "J", "K", "L", "M", "N", "P", "Q", "R", "S", "T", "V", "W", "Y", "Z", "AA", "BB", "CC", "DD", "EE", "FF", "GG", "HH"
B12dCd	string	Enter the Box 12d Code. Allowed values: "A", "B", "C", "D", "E", "F", "G", "H", "J", "K", "L", "M", "N", "P", "Q", "R", "S", "T", "V", "W", "Y", "Z", "AA", "BB", "CC", "DD", "EE", "FF", "GG", "HH"
B13IsStatEmp	Boolean	When true, identifies the statutory employees whose earnings are subject to social security and Medicare taxes but not subject to federal income tax withholding. They are independent contractors under the common-law rules but are treated by statute as employees.
B13IsRetPlan	Boolean	When true, identifies if the employee is an active participant of a retirement plan.
B13Is3rdPartySickPay	Boolean	When true, identifies if the business reports third-party sick pay.
B14Other	string	Gets any additional information that the employer wants to give to employees that cannot be reported in boxes 1-13. Examples include auto allowance, travel reimbursement, relocation expenses, job uniforms, after-tax employee contributions to an HSA, etc. Size Range: 1..51
ControlNum	string	Identifies individual Forms W-2 and this box is optional.
States	object[]	Contains list of state returns information.
B15StateCd	string	State Code of Employer's State. Size Range: 2 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"
B15StateIdNum	string	Identification Number of Employer's State. Size Range: ..20
B16StateWages	number	Amount of Wages, tips, etc for State. Size Range: 0-999999999.99
B17StateTax	number	Income Tax of State. Size Range: 0-999999999.99
LocalityData	object[]	Contains list of locality information about the state.
LocalWages	number	Amount of Local Wages, tips, etc for State. Size Range: 0-999999999.99
LocalTax	number	Local Income Tax of State. Size Range: 0-999999999.99
LocalityNm	string	Locality name of State.
TaxTypeCd	enum	Enter the Tax Type Code for the amount entered in "LocalWages" and "LocalTax". Allowed values: "C City Income Tax", "D County Income Tax", "E School District Income Tax", "F Other Income Tax"
County	enum	Enter the Indiana County code if the "TaxTypeCd" code is "D" - County Income Tax. Allowed values: "Adams", "Allen", "Bartholomew", "Benton", "Blackford", "Boone", "Brown", "Carrol", "Cass", "Clark", "Clay", "Clinton", "Crawford", "Daviess", "Dearborn", "Decatur", "DeKalb", "Delaware", "Dubois", "Elkhart", "Fayette", "Floyd", "Fountain", "Franklin", "Fulton", "Gibson", "Grant", "Greene", "Hamilton", "Hancock", "Harrison", "Hendricks", "Henry", "Howard", "Huntington", "Jackson", "Jasper", "Jay", "Jefferson", "Jennings", "Johnson", "Knox", "Kosciusko", "LaGrange", "Lake", "LaPorte", "Lawrence", "Madison", "Marion", "Marshall", "Martin", "Miami", "Monroe", "Montgomery", "Morgan", "Newton", "Noble", "Ohio", "Orange", "Owen", "Parke", "Perry", "Pike", "Porter", "Posey", "Pulaski", "Putnam", "Randolph", "Ripley", "Rush", "St.Joseph", "Scott", "Shelby", "Spencer", "Starke", "Steuben", "Sullivan", "Switzerland", "Tippecanoe", "Tipton", "Union", "Vanderburgh", "Vermillion", "Vigo", "Wabash", "Warren", "Warrick", "Washington", "Wayne", "Wells", "White", "Whitley"
SchoolDistrictNum	string	Enter the School District Number if the "TaxTypeCd" is "E" - School District Income Tax.
EmployeeStateSpecificData	object	Contains employee specific data for the selected states.
KS	object	Contains employee state specific data for Kansas.
EmployeeContribution	number	Enter the amount of Employee Contribution to KPERS, KP & F and Judges. Size Range: 0-999999999.99
ME	object	Contains employee state specific data for Maine.
MEPERScontribution	number	Enter the amount of pick-up contributions deducted from this employee’s salary and contributed to MEPERS on behalf of the employee. Size Range: 0-999999999.99
MD	object	Contains employee state specific data for Maryland.
W4ExemptionCount	int	Enter the number of exemptions claimed on Form W-4.
NJ	object	Contains employee state specific data for New Jersey.
PvtFmlLeaveInsuranceNum	string	Enter the Private Family Leave Insurance Plan Number. Size Range: ..14
FmlLeaveInsuranceWH	number	Enter the amount withheld as Family Leave Insurance workers contributions. Size Range: 0-999.99
PvtDisabilityPlanNum	string	Enter the Private Disability Plan Number. Size Range: ..14
DisabilityInsuranceWH	number	Enter the amount withheld as workers’ contributions for Disability Insurance. Size Range: 0-999.99
CombNJUnempInsWrkFrceDevProgHCSubWH	number	Enter the amount withheld as workers contributions for Combined NJ unemployment insurance, Workforce Development Program and health Care Subsidy. Size Range: 0-999.99
DeffCompAmt	number	Enter the total employee elective deferrals to a Code Section 401(k) plan, made during the year. Size Range: 0-9999999.99
IsRetirementPlan	Boolean	When TRUE, identifies that the employee was an active participant (for any part of the year) in a retirement plan.
OR	object	Contains employee state specific data for Oregon.
DateFirstEmployed	date	Enter the date first employed.
DateOfSeparation	date	Enter the date of separation.
TaxableWagesForStateTransitTax	number	Enter the State Taxable Wages for Statewide Transit Tax. Size Range: 0-999999999.99
StateTransitTaxWH	number	Enter the Statewide Transit Tax Withheld. Size Range: 0-999999999.99
MA	object	Contains employee state specific data for Massachusetts.
EeContributionMAPFML	number	Enter the Employee contribution for Paid Family and Medical Leave. Size Range: 0-999999999.99
StateReconData	object	Collects State Recon fields specific for each state. Click here, for the description of each state specific Recon fields.

Response Body

Field	Type	Description
StatusCode	number	Returns the HTTP status codes like 200,300 etc.
StatusName	string	Name of the status code
StatusMessage	string	Detailed status message
SubmissionId	Guid	Unique identifier of a submission
BusinessId	Guid	Unique identifier of a Business.
PayerRef	string	Unique identifier of a Payer.
FormW2Records	object	Pulls the Form W-2 records with Success and Error statuses
SuccessRecords	object[]	It will show the detailed information about the success status of Form W2 Records
SequenceId	string	An 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.
RecordId	Guid	An unique identifier generated by TaxBandits when a W2 return is created.
EmployeeId	Guid	An unique identifier generated by TaxBandits for a employee when a W2 return is created. You can use this id for your future reference to Update.
FederalReturn	object	Returns the record status and StatusTs of federal return.
Status	string	Returns the record status.
StatusTs	string	Returns date and time of return created.
Info	string	Returns information about the Federal Filing service.
StateReturns	object[]	Returns collection of state returns information
StateCd	string	Returns the state code of the state for which the return is filed.
Status	string	Returns the record status of the state return.
StatusTs	string	Date and time of the return created.
Info	string	Returns the information about the state for which we are not supporting state filing.
Errors	object[]	Shows error information of state returns of Form W2
Id	string	Returns the validation error Id.
Name	string	Name of the validation error.
Message	string	Description of the validation error.
Postal	object	Returns the status and StatusTs of postal mailing service for Form W2.
Status	string	Returns the status of postal order.
StatusTs	string	Returns the date and time of the postal order created.
Info	string	Returns the information about Postal mailing service.
OnlineAccess	object	Returns the Email address for whom the online access to be given and Status of online access.
Status	string	Returns the Status of the Online Access.
Email	string	Email address for whom the online access to be given.
Info	string	Information about the online access service.
ScheduleFiling	object	Returns the date of the schedule filing.
ScheduledOn	string	Date of the schedule filing to know when the return to be filed to the IRS.
Info	string	Information about Schedule Filing service.
ErrorRecords	object[]	It will show the detailed information about the error status of Form W2 Records.
SequenceId	string	An 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.
RecordId	Guid	Unique identifier of a record
Errors	object[]	Shows detailed error information
Id	string	Returns the validation error Id
Name	string	Name of the validation error
Message	string	Description of the validation error
Errors	object[]	Shows detailed error information
Id	string	Returns the validation error Id
Name	string	Name of the validation error
Message	string	Description of the validation error

Request JSON

{
 "SubmissionManifest": {
   "SubmissionId": "ef869fda-5562-41c8-b0d2-b61ef19a2f5a",
   "TaxYear": "2021",
   "IsFederalFiling": true,
   "IsStateFiling": true,
   "IsPostal": false,
   "IsOnlineAccess": true,
   "IsScheduleFiling": false,
   "ScheduleFiling": null
 },
 "ReturnHeader": {
   "Business": {
     "BusinessId": "668e8869-ef32-4292-a9a7-b44c097647e5",
     "PayerRef": "Pe123",
     "BusinessNm": "Brian LLC",
     "TradeNm": "Brian Corporate Services",
     "IsEIN": true,
     "Email": "brianscott@gmail.com",
     "ContactNm": "Brian O Relly",
     "Phone": "1234447890",
     "PhoneExtn": "12345",
     "Fax": "4567893120",
     "BusinessType": "ESTE",
     "SigningAuthority": {
       "Name": "Altof",
       "Phone": "1234578960",
       "BusinessMemberType": "ADMINISTRATOR"
     },
     "KindOfEmployer": "FEDERALGOVT",
     "KindOfPayer": "REGULAR941",
     "IsBusinessTerminated": true,
     "IsForeign": true,
     "USAddress": {
       "Address1": "1751 Kinsey Rd",
       "Address2": "Main St",
       "City": "Dothan",
       "State": "AL",
       "ZipCd": "36303"
     },
     "ForeignAddress": {
       "Address1": "500 Penn Avenue",
       "Address2": "Park Street",
       "City": "Toronto",
       "ProvinceOrStateNm": "Ontario",
       "Country": "CA",
       "PostalCd": "02452"
     }
   }
 },
 "ReturnData": [
   {
     "RecordId": "566e1623-3c07-4d15-9fcc-00cad9a3a5d5",
     "SequenceId": "001",
     "Employee": {
       "EmployeeId": "efee6e99-e861-48fb-9c82-61d0f9e0c97f",
       "FirstNm": "Mianic6",
       "MiddleNm": "George",
       "LastNm": "Augustin",
       "Suffix": "Sr",
       "Email": "mike@gmail.com",
       "Fax": "4567891234",
       "Phone": "4259631478",
       "IsForeign": false,
       "USAddress": {
         "Address1": "1751 Kinsey Rd",
         "Address2": "Main St",
         "City": "Dothan",
         "State": "AL",
         "ZipCd": "36303"
       },
       "ForeignAddress": {
         "Address1": "500 Penn Avenue",
         "Address2": "Park Street",
         "City": "Toronto",
         "ProvinceOrStateNm": "Ontario",
         "Country": "CA",
         "PostalCd": "02452"
       }
     },
     "W2FormData": {
       "B1Wages": 50000.65,
       "B2FedTaxWH": 5263.32,
       "B3SocSecWages": 137000,
       "B4SocSecTaxWH": 46.15,
       "B5MediWages": 137700,
       "B6MediTaxWH": 78.21,
       "B7SocSecTips": 700,
       "B8AllocatedTips": 45,
       "B10DependtCareBenefits": 78,
       "B11Sec457Plan": 96,
       "B11NonSec457Plan": 0,
       "B12aCd": "EE",
       "B12aAmt": 32,
       "B12bCd": "B",
       "B12bAmt": 21,
       "B12cCd": "E",
       "B12cAmt": 213,
       "B12dCd": "H",
       "B12dAmt": 210,
       "B13IsStatEmp": true,
       "B13IsRetPlan": true,
       "B13Is3rdPartySickPay": true,
       "B14Other": "Real Estate 4500",
       "ControlNum": "35231",
       "States": [
         {
           "B15StateCd": "IN",
           "B15StateIdNum": "9999999999 999",
           "B16StateWages": 1000,
           "B17StateTax": 100,
           "LocalityData": [
             {
               "LocalWages": 300.23,
               "LocalTax": 100.45,
               "LocalityNm": "Pristine",
               "County": "adams",
               "TaxTypeCd": null,
               "SchoolDistrictNum": null
             }
           ]
         },
         {
           "B15StateCd": "VT",
           "B15StateIdNum": "WHT98765121",
           "B16StateWages": 500000.65,
           "B17StateTax": 5263.32,
           "LocalityData": [
             {
               "LocalWages": 300.23,
               "LocalTax": 100.45,
               "LocalityNm": "Pristine",
               "TaxTypeCd": null,
               "County": null,
               "SchoolDistrictNum": null
             }
           ]
         },
         {
           "B15StateCd": "PA",
           "B15StateIdNum": "99999999",
           "B16StateWages": 1000,
           "B17StateTax": 100,
           "LocalityData": [
             {
               "LocalWages": 300.23,
               "LocalTax": 100.45,
               "LocalityNm": "Pristine",
               "TaxTypeCd": null,
               "County": null,
               "SchoolDistrictNum": null
             }
           ]
         },
         {
           "B15StateCd": "KS",
           "B15StateIdNum": "036499993579F10",
           "B16StateWages": 50000.65,
           "B17StateTax": 0,
           "LocalityData": [
             {
               "LocalWages": 300.23,
               "LocalTax": 100.45,
               "LocalityNm": "Pristine",
               "TaxTypeCd": null,
               "County": null,
               "SchoolDistrictNum": null
             }
           ]
         }
       ],
       "EmployeeStateSpecificData": {
         "KS": {
           "EmployeeContribution": 251.55
         }
       }
     }
   }
 ],
 "StateReconData": {
   "IN": {
     "FormWH3": {
       "INWithHoldingID": "4657385932 254",
       "NumOfW2WH18W2G1099Forms": 23,
       "StateTaxWHW2WH18W2G1099": 100,
       "CountyTaxWHW2WH18W2G1099": 100,
       "TotTaxWH": 200,
       "TotDeposits": 500,
       "BalDue": 0,
       "OverPayment": 300,
       "CountyTaxWH": [
         {
           "CountyNm": "Adams",
           "TaxWH": 50
         },
         {
           "CountyNm": "Decatur",
           "TaxWH": 50
         }
       ],
       "TotCountyTaxWH": 100
     }
   },
   "VT": {
     "FormWHT434": {
       "VTWithHoldingID": "WHT98765101",
       "PayFreq": "Quarterly",
       "IsBusinessCeasedWantToCloseAcc": "True",
       "BusinessCeaseDate": "07/10/2021",
       "IsReportingSickPay": "True",
       "AggErHealthInsCoverage": 210,
       "TotNumOfW2Forms": 15,
       "TotWagesPerW2": 1000,
       "TaxWHPerW2": 200,
       "TotNumOf1099Forms": 16,
       "Tot1099Payments": 1000,
       "TaxWHPer1099": 201,
       "TotTaxWH": 401,
       "IsPaidPreparer": "True"
     }
   },
   "PA": {
     "FormREV1667": {
       "PAWithHoldingID": 45734565,
       "TotNumOfW2": 4,
       "TotNumOf1099R": 0,
       "TotNumOf1099NECMISC": 0,
       "TotWagesAndDistribution": 1000,
       "TotTaxWH": 0,
       "WagesAndDistribution": {
         "Qtr1": "100",
         "Qtr2": "100",
         "Qtr3": "100",
         "Qtr4": "700",
         "TotWagesAllQtrs": 1000
       },
       "TaxWH": {
         "Qtr1": "0",
         "Qtr2": "0",
         "Qtr3": "0",
         "Qtr4": "0",
         "TotTaxWHAllQtrs": 0
       }
     }
   },
   "KS": {
     "FormKW3": {
       "KSWithHoldingID": "036999999999F99",
       "WHAccClosedDate": null,
       "NumOf1099W2Forms": 1,
       "TotTaxWH1099W2": 100,
       "WHTaxPaid": 49,
       "CreditAvailable": 50,
       "TotWHPayment": 99,
       "Overpayment": 0,
       "BalanceDue": 1,
       "Penalty": 0,
       "Interest": 0,
       "TotTax": 1,
       "FilingSchType": "Quarterly",
       "Quarterly": {
         "Qtr1": 99,
         "Qtr2": 0,
         "Qtr3": 0,
         "Qtr4": 0
       },
       "Monthly": null,
       "SemiMonthly": null,
       "QuadMonthly": null,
       "Annual": null,
       "TotPayments": 99
     }
   }
 }
}

Response JSON

{
 "StatusCode": 200,
 "StatusName": "Ok",
 "StatusMessage": "Successful API call",
 "SubmissionId": "ef869fda-5562-41c8-b0d2-b61ef19a2f5a",
 "BusinessId": "668e8869-ef32-4292-a9a7-b44c097647e5",
 "PayerRef": "Pe123",
 "FormW2Records": {
   "SuccessRecords": [
     {
       "SequenceId": "001",
       "RecordId": "566e1623-3c07-4d15-9fcc-00cad9a3a5d5",
       "EmployeeId": "efee6e99-e861-48fb-9c82-61d0f9e0c97f",
       "FederalReturn": {
         "Status": "CREATED",
         "StatusTs": "2021-08-06 10:28:47 -04:00",
         "Info": null
       },
       "StateReturns": [
         {
           "StateCd": "IN",
           "Status": "CREATED",
           "StatusTs": "2021-08-06 10:28:47 -04:00",
           "Info": null,
           "Errors": null
         },
         {
           "StateCd": "VT",
           "Status": "CREATED",
           "StatusTs": "2021-08-06 10:28:47 -04:00",
           "Info": null,
           "Errors": null
         },
         {
           "StateCd": "PA",
           "Status": "CREATED",
           "StatusTs": "2021-08-06 10:28:47 -04:00",
           "Info": null,
           "Errors": null
         },
         {
           "StateCd": "KS",
           "Status": "CREATED",
           "StatusTs": "2021-08-06 10:28:47 -04:00",
           "Info": null,
           "Errors": null
         }
       ],
       "Postal": null,
       "OnlineAccess": {
            "Status": "CREATED",
            "Email": "john@gmail.com",
            "Info": null
       },
       "ScheduleFiling": null
     }
   ],
   "ErrorRecords": null
 },
 "Errors": null
}

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

# Validate

VALIDATE being an optional endpoint, can be used prior transmitting the returns to validate those returns against the business rules. This endpoint requires the Submission ID & Record ID(s) to be sent in the request.

GET FormW2/Validate

Request Body

Field	Type	Description
SubmissionId	Guid	Unique identifier of a submission
RecordIds	Guid[]	An unique identifier generated by TaxBandits when a W2 return is created. Mention the W2 return's Record ID that you want to Validate.

Response Body

Field	Type	Description
StatusCode	number	Returns the HTTP status codes like 200,300 etc.
StatusName	string	Name of the status code
StatusMessage	string	Detailed status message
SubmissionId	Guid	Unique identifier of a submission
FormW2Records	object	Pulls the Form W-2 records with Success and Error statuses
SuccessRecords	object[]	It will show the detailed information about the success status of Form W2 Records
SequenceId	string	An 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.
RecordId	Guid	Unique identifier of a record
Status	string	Returns the status of the records.
StatusTs	string	Date and time of return created.
StateReturns	object[]	Returns the state code and return status.
StateCode	string	Returns the code of the state.
RecordStatus	string	Returns the status of the records.
ErrorRecords	object[]	It will show the detailed information about the error status of Form W2 Records.
RecordId	Guid	Unique identifier of a record
SequenceId	string	An 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.
RejectedBy	string	Returns the information of who rejected the return.
Errors	object[]	Shows detailed error information
Id	string	Returns the validation error Id
Name	string	Name of the validation error
Message	string	Description of the validation error
Errors	object[]	Shows detailed error information
Code	string	Returns the validation error Id
Name	string	Name of the validation error
Message	string	Description of the validation error

Request JSON

FormW2/Validate?SubmissionId=d1f9cb0a-912f-4105-8bcf-059af43d2b31&RecordIds=a4718eab-e144-4c54-b502-3c00c3dd61b9,8e0db3cb-965e-4618-a36d-75684501d38f

Response JSON

{
 "StatusCode": 200,
 "StatusName": "Ok",
 "StatusMessage": "Successful API call",
 "SubmissionId": "f6683d71-448c-4a69-aa17-e58c6ef085ab",
 "FormW2Records": {
   "SuccessRecords": [
     {
       "SequenceId": "1",
       "RecordId": "a4718eab-e144-4c54-b502-3c00c3dd61b9",
       "Status": "Created",
       "StatusTs": "2021-08-05 09:10:45 -04:00",
       "StateReturns": [
         {
           "StateCode": "SC",
           "RecordStatus": "Created"
         },
         {
           "StateCode": "DE",
           "RecordStatus": "Created"
         }
       ]
     },
     {
       "SequenceId": "1",
       "RecordId": "8e0db3cb-965e-4618-a36d-75684501d38f",
       "Status": "Created",
       "StatusTs": "2021-08-05 09:10:45 -04:00",
       "StateReturns": [
         {
           "StateCode": "SC",
           "RecordStatus": "Created"
         },
         {
           "StateCode": "DE",
           "RecordStatus": "Created"
         }
       ]
     }
   ],
   "ErrorRecords": null
 },
 "Errors": null
}

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

# ValidateForm

An optional API Endpoint to validate a Tax Return. The API Endpoints “CREATE” and “TRANSMIT” also do the same validation functionality. One important difference is that the ValidateForm Endpoint does not require the Tax Return to be created. You can validate the tax data and then call the create or transmit endpoints to create the tax return.

POST FormW2/ValidateForm

Request Body

Field	Type	Description
SubmissionManifest	object	SubmissionManifest provides the brief information about a particular submission on the whole. It contains information like Submission ID, Tax Year, IsPostal, IsFederalFiling, IsStateFiling, IsOnlineAccess, IsScheduleFiling & ScheduleFiling service details.
SubmissionId	Guid	Unique identifier created by TaxBandits for each submission. Not required when you are creating a return.
TaxYear	string	Tax year of Form W2 to be filed. Allowed values: "2021"
IsFederalFiling	Boolean	Federal Filing for the return will be enabled when the value is True. Form W2 will be sent directly to the IRS.
IsStateFiling	Boolean	State Filing for the return will be enabled when the value is True. Form W2 will be directly filed with the respective employee states. Note: State Filing will not be created for the states that do not require State filing.
IsPostal	Boolean	Postal Order will be created when the value is set as True. Once the return is Transmitted, Form W2 employee copies will be postal mailed to the employee's address via USPS. Note: Postal Orders for Foreign Address will not be created.
IsOnlineAccess	Boolean	Online Access will be enabled when the value is set as True. Once the return is Transmitted, an email with the link to the secure TaxBandits portal will be sent to the employee. The employee can provide consent and download Form W2 employee copies from the portal.
IsScheduleFiling	Boolean	When true, schedule filing services will be provided for W2 returns under this submission.
ScheduleFiling	object	Contains preferred date to submit the returns to the IRS. 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: 10/20/2021 or 10-20-2021
ReturnHeader	object	Contains information about the Business details.
Business	object	Object to identify the Business Details.
BusinessId	Guid	Use the unique Business ID (Generated by TaxBandits), you received in the response of the Business CREATE Endpoint. If you have 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.
BusinessNm	string	Name of the business Size Range: ..75
TradeNm	string	`Optional` Name under which the business operates Size Range: ..75
IsEIN	Boolean	When true, identifies the business with an EIN.
EINorSSN	string	Enter the Employer Identification Number (EIN) as you are filing Form W-2. You can not file Form W-2 with your SSN. Size Range: 9
Email	string	Email address of the Business Size Range: ..40
ContactNm	string	`Optional` Name of the person who can be contacted by the IRS Size Range: ..27
Phone	string	Phone number of the business Size Range: 10
PhoneExtn	string	`Optional` Extension of the business phone number Size Range: ..5
Fax	string	`Optional` Fax number of the Business Size Range: 10
BusinessType	string	`Optional` Type of business. Optional for W-2/1099 and mandatory for 94X series Size Range: 4 Allowed values: "ESTE", "PART", "CORP", "EORG", "SPRO"
SigningAuthority	object	`Optional` Details of the person who is authorized to sign the return
Name	string	`Optional` Name of the signing authority Size Range: ..35
Phone	string	`Optional` Phone number of the signing authority Size Range: 10
BusinessMemberType	string	`Optional` Business title of the signing authority Size Range: 5..29 Allowed values: "CORPORATESECRETARY", "SECRETARYTREASURER", "PARTNER", "GENERALPARTNER", "LIMITEDPARTNER", "LLCMEMBER", "MANAGINGMEMBER", "MANAGER", "TAXMATTERPARTNER", "PRESIDENT", "VICEPRESIDENT", "CORPORATETREASURER", "TREASURER", "ASSISTANTTREASURER", "CHIEFACCOUNTINGOFFICER", "CHIEFEXECUTIVEOFFICER", "CHIEFFINANCIALOFFICER", "TAXOFFICER", "CHIEFOPERATINGOFFICER", "CORPORATEOFFICER", "EXECUTIVEDIRECTOR", "DIRECTOR", "CHAIRMAN", "EXECUTIVEADMINISTRATOR", "RECEIVER", "PASTOR", "ASSISTANTTORELIGIOUSLEADER", "REVEREND", "PRIEST", "MINISTER", "RABBI", "LEADEROFRELIGIOUSORGANIZATION", "SECRETARY", "DIRECTOROFTAXATION", "DIRECTOROFPERSONNEL", "ADMINISTRATOR", "EXECUTOR", "TRUSTEE", "FIDUCIARY", "OWNER", "SOLEPROPRIETOR", "MEMBER", "SOLEMEMBER"
KindOfEmployer	string	`Optional` Identifies the kind of employer. Mandatory for W-2 and optional for 1099-MISC and 94X series Allowed values: "FEDERALGOVT", "STATEORLOCAL501C", "NONGOVT501C", "STATEORLOCALNON501C", "NONEAPPLY"
KindOfPayer	string	`Optional` Identifies the kind of payer. This field is mandatory in W-2 and optional in 1099-MISC and 94X series Allowed values: "REGULAR941", "REGULAR944", "AGRICULTURAL943", "HOUSEHOLD", "MILITARY", "MEDICAREQUALGOVEM", "RAILROADFORMCT1"
IsBusinessTerminated	Boolean	When true, identifies the business as terminated.
IsForeign	Boolean	When true, identifies the business address with a foreign address.
USAddress	object	If IsForeign is false, pass US address of the business
Address1	string	Employer/Payer's US address (street address or post office box of that locality) Size Range: ..35
Address2	string	`Optional` Employer/Payer's suite or apartment Size Range: ..35
City	string	Employer/Payer's city Size Range: ..27
State	string	Employer/Payer's state code. Refer Static values. Size Range: 2 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"
ZipCd	string	Employer/Payer's zip code
ForeignAddress	object	If IsForeign is true, pass foreign address of the business
Address1	string	Employer/Payer's foreign address (street address or post office box of that locality) Size Range: ..35
Address2	string	`Optional` Employer/Payer's suite or apartment Size Range: ..35
City	string	Employer/Payer's city Size Range: ..27
ProvinceOrStateNm	string	Employer/Payer's province or state name Size Range: ..30
Country	string	Employer/Payer's country Size Range: 2 Allowed values: "US", "CA", "MX", "AF", "AX", "XI", "AL", "AG", "AQ", "AN", "AO", "AV", "AY", "AC", "AR", "AM", "AA", "XA", "AT", "AS", "AU", "AJ", "XZ", "BF", "BA", "FQ", "BG", "BB", "BS", "BO", "BE", "BH", "BN", "BD", "BT", "BL", "BK", "BC", "BV", "BR", "IO", "VI", "BX", "BU", "UV", "BM", "BY", "CB", "CM", "XY", "CV", "CJ", "CT", "CD", "XC", "CI", "CH", "KT", "IP", "CK", "CO", "CN", "CF", "CG", "CW", "CR", "VP", "CS", "IV", "HR", "CU", "CY", "EZ", "DA", "DX", "DJ", "DO", "DR", "TT", "EC", "EG", "ES", "UK", "EK", "ER", "EN", "ET", "EU", "FK", "FO", "FM", "FJ", "FI", "FR", "FG", "FP", "FS", "GB", "GA", "GZ", "GG", "GM", "GH", "GI", "GO", "GR", "GL", "GJ", "GP", "GQ", "GT", "GK", "GV", "PU", "GY", "HA", "HM", "HO", "HK", "HQ", "HU", "IC", "IN", "ID", "IR", "IZ", "EI", "IS", "IT", "JM", "JN", "JA", "DQ", "JE", "JQ", "JO", "JU", "KZ", "KE", "KQ", "KR", "KN", "KS", "KU", "KG", "LA", "LG", "LE", "LT", "LI", "LY", "LS", "LH", "LU", "MC", "MK", "MA", "MI", "MY", "MV", "ML", "MT", "IM", "RM", "MB", "MR", "MP", "MF", "MQ", "MD", "MN", "MG", "MJ", "MH", "MO", "MZ", "XM", "WA", "NR", "BQ", "NP", "NL", "NT", "NC", "NZ", "NU", "NG", "NI", "NE", "NF", "XN", "CQ", "NO", "MU", "OC", "PK", "LQ", "PS", "PM", "PP", "PF", "PA", "PE", "RP", "PC", "PL", "PO", "RQ", "QA", "RE", "RO", "RS", "RW", "WS", "SM", "TP", "SA", "XS", "SG", "RI", "SE", "SL", "SN", "XR", "LO", "SI", "BP", "SO", "SF", "SX", "SP", "PG", "CE", "SH", "SC", "ST", "SB", "VC", "SU", "NS", "SV", "WZ", "SW", "SZ", "SY", "TW", "TI", "TZ", "TH", "TO", "TL", "TN", "TD", "XT", "TE", "TS", "TU", "TX", "TK", "TV", "UG", "UP", "AE", "UY", "UZ", "NH", "VT", "VE", "VM", "VQ", "WQ", "XW", "WF", "WE", "WI", "YM", "YI", "ZA", "ZI"
PostalCd	string	Employer/Payer's postal code
ReturnData	object[]	Contains information about the employee details and Form W2 details.
SequenceId	string	An 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
RecordId	Guid	Unique identifier of a record. Not required when you are creating a return.
Employee	object	Object to identify the employee details.
EmployeeId	Guid	An unique ID generated by TaxBandits after the return is created and will be returned in the Response. You can use this id for your future reference to Update.
SSN	string	Employee's Social Security Number (SSN) Size Range: 9
FirstNm	string	Employee's first name.
MiddleNm	string	`Optional` Employee's middle name.
LastNm	string	Employee's last name.
Suffix	string	`Optional` Employee's suffix. Allowed values: "Jr", "Sr", "I", "II", "III", "IV", "V", "VI", "VII"
Email	string	`Optional` Employee's email address. Size Range: 0..40
Fax	string	`Optional` Employee's fax number. Size Range: 10
Phone	string	`Optional` Employee's phone number. Size Range: 10
IsForeign	Boolean	When true, identifies the employee address with a foreign address.
USAddress	object	Object to identify the employee's US address
Address1	string	Employee's US address (street address or post office box of that locality) Size Range: ..35
Address2	string	Employee's suite or apartment Size Range: ..35
City	string	Employee's city Size Range: ..27
State	string	Employee's State code. Refer Static values. Size Range: 2 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"
ZipCd	string	Employee's zip code
ForeignAddress	object	If IsForeign is true, pass foreign address of the employee
Address1	string	Employee's foreign address (street address or post office box of that locality) Size Range: ..35
Address2	string	`Optional` Employee's suite or apartment Size Range: ..35
City	string	Employee's city. Size Range: ..27
ProvinceOrStateNm	string	Employee's Province or State Name. Size Range: ..30
Country	string	Employee's country code. Refer Static values. Size Range: 2 Allowed values: "US", "CA", "MX", "AF", "AX", "XI", "AL", "AG", "AQ", "AN", "AO", "AV", "AY", "AC", "AR", "AM", "AA", "XA", "AT", "AS", "AU", "AJ", "XZ", "BF", "BA", "FQ", "BG", "BB", "BS", "BO", "BE", "BH", "BN", "BD", "BT", "BL", "BK", "BC", "BV", "BR", "IO", "VI", "BX", "BU", "UV", "BM", "BY", "CB", "CM", "XY", "CV", "CJ", "CT", "CD", "XC", "CI", "CH", "KT", "IP", "CK", "CO", "CN", "CF", "CG", "CW", "CR", "VP", "CS", "IV", "HR", "CU", "CY", "EZ", "DA", "DX", "DJ", "DO", "DR", "TT", "EC", "EG", "ES", "UK", "EK", "ER", "EN", "ET", "EU", "FK", "FO", "FM", "FJ", "FI", "FR", "FG", "FP", "FS", "GB", "GA", "GZ", "GG", "GM", "GH", "GI", "GO", "GR", "GL", "GJ", "GP", "GQ", "GT", "GK", "GV", "PU", "GY", "HA", "HM", "HO", "HK", "HQ", "HU", "IC", "IN", "ID", "IR", "IZ", "EI", "IS", "IT", "JM", "JN", "JA", "DQ", "JE", "JQ", "JO", "JU", "KZ", "KE", "KQ", "KR", "KN", "KS", "KU", "KG", "LA", "LG", "LE", "LT", "LI", "LY", "LS", "LH", "LU", "MC", "MK", "MA", "MI", "MY", "MV", "ML", "MT", "IM", "RM", "MB", "MR", "MP", "MF", "MQ", "MD", "MN", "MG", "MJ", "MH", "MO", "MZ", "XM", "WA", "NR", "BQ", "NP", "NL", "NT", "NC", "NZ", "NU", "NG", "NI", "NE", "NF", "XN", "CQ", "NO", "MU", "OC", "PK", "LQ", "PS", "PM", "PP", "PF", "PA", "PE", "RP", "PC", "PL", "PO", "RQ", "QA", "RE", "RO", "RS", "RW", "WS", "SM", "TP", "SA", "XS", "SG", "RI", "SE", "SL", "SN", "XR", "LO", "SI", "BP", "SO", "SF", "SX", "SP", "PG", "CE", "SH", "SC", "ST", "SB", "VC", "SU", "NS", "SV", "WZ", "SW", "SZ", "SY", "TW", "TI", "TZ", "TH", "TO", "TL", "TN", "TD", "XT", "TE", "TS", "TU", "TX", "TK", "TV", "UG", "UP", "AE", "UY", "UZ", "NH", "VT", "VE", "VM", "VQ", "WQ", "XW", "WF", "WE", "WI", "YM", "YI", "ZA", "ZI"
PostalCd	string	Employee's Postal Code
W2FormData	object	Employee's Form W-2 information
B1Wages	number	Gets the total taxable wages, tips, and other compensation paid by the employer to employees during the year. These figures should be prior to payroll deductions. Size Range: 0-999999999.99
B2FedTaxWH	number	Gets the total federal income tax withheld from the employee's wages for the year. Include the 20% excise tax withheld on excess parachute payments. Size Range: 0-999999999.99
B3SocSecWages	number	Gets the total wages paid (before payroll deductions) subject to employee social security tax. Size Range: 0-999999999.99
B4SocSecTaxWH	number	Gets the total amount of social security tax withheld from employees. Include only taxes withheld for wages and tips. Size Range: 0-999999999.99
B5MediWages	number	Gets the amount of wages and tips subject to medicare tax. These are similar to those subject to social security tax (boxes 3 and 7) except that there is no wage base limit for Medicare tax. Size Range: 0-999999999.99
B6MediTaxWH	number	Gets the amount of taxes withheld from employees for Medicare tax Size Range: 0-999999999.99
B7SocSecTips	number	Gets the tips reported by the employee for which the employer did not have enough employee funds to collect the social security tax for the tips. Size Range: 0-999999999.99
B8AllocatedTips	number	Gets the tips allocated to your employee if you operate a large food or beverage establishment. Size Range: 0-999999999.99
B10DependtCareBenefits	number	Gets the total amount of dependent care benefits paid or incurred by the employer for employees under a dependent care assistance program. Size Range: 0-999999999.99
B11Sec457Plan	number	Gets the amount distributed to an employee from the employer's non-qualified plan Size Range: 0-999999999.99
B11NonSec457Plan	number	Gets the amount distributed to an employee from the employer's non-governmental section 457(b) plan Size Range: 0-999999999.99
B12aAmt	number	Enter the amount value for the code selected under Box 12a. Size Range: 0-999999999.99
B12bAmt	number	Enter the amount value for the code selected under Box 12b. Size Range: 0-999999999.99
B12cAmt	number	Enter the amount value for the code selected under Box 12c. Size Range: 0-999999999.99
B12dAmt	number	Enter the amount value for the code selected under Box 12d. Size Range: 0-999999999.99
B12aCd	string	Enter the Box 12a Code. Allowed values: "A", "B", "C", "D", "E", "F", "G", "H", "J", "K", "L", "M", "N", "P", "Q", "R", "S", "T", "V", "W", "Y", "Z", "AA", "BB", "CC", "DD", "EE", "FF", "GG", "HH"
B12bCd	string	Enter the Box 12b Code. Allowed values: "A", "B", "C", "D", "E", "F", "G", "H", "J", "K", "L", "M", "N", "P", "Q", "R", "S", "T", "V", "W", "Y", "Z", "AA", "BB", "CC", "DD", "EE", "FF", "GG", "HH"
B12cCd	string	Enter the Box 12c Code. Allowed values: "A", "B", "C", "D", "E", "F", "G", "H", "J", "K", "L", "M", "N", "P", "Q", "R", "S", "T", "V", "W", "Y", "Z", "AA", "BB", "CC", "DD", "EE", "FF", "GG", "HH"
B12dCd	string	Enter the Box 12d Code. Allowed values: "A", "B", "C", "D", "E", "F", "G", "H", "J", "K", "L", "M", "N", "P", "Q", "R", "S", "T", "V", "W", "Y", "Z", "AA", "BB", "CC", "DD", "EE", "FF", "GG", "HH"
B13IsStatEmp	Boolean	When true, identifies the statutory employees whose earnings are subject to social security and Medicare taxes but not subject to federal income tax withholding. They are independent contractors under the common-law rules but are treated by statute as employees.
B13IsRetPlan	Boolean	When true, identifies if the employee is an active participant of a retirement plan.
B13Is3rdPartySickPay	Boolean	When true, identifies if the business reports third-party sick pay.
B14Other	string	Gets any additional information that the employer wants to give to employees that cannot be reported in boxes 1-13. Examples include auto allowance, travel reimbursement, relocation expenses, job uniforms, after-tax employee contributions to an HSA, etc. Size Range: 1..51
ControlNum	string	Identifies individual Forms W-2 and this box is optional.
States	object[]	Contains list of state returns information.
B15StateCd	string	State Code of Employer's State. Size Range: 2 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"
B15StateIdNum	string	Identification Number of Employer's State. Size Range: ..20
B16StateWages	number	Amount of Wages, tips, etc for State. Size Range: 0-999999999.99
B17StateTax	number	Income Tax of State. Size Range: 0-999999999.99
LocalityData	object[]	Contains list of locality information about the state.
LocalWages	number	Amount of Local Wages, tips, etc for State. Size Range: 0-999999999.99
LocalTax	number	Local Income Tax of State. Size Range: 0-999999999.99
LocalityNm	string	Locality name of State.
TaxTypeCd	enum	Enter the Tax Type Code for the amount entered in "LocalWages" and "LocalTax". Allowed values: "C City Income Tax", "D County Income Tax", "E School District Income Tax", "F Other Income Tax"
County	enum	Enter the Indiana County code if the "TaxTypeCd" code is "D" - County Income Tax. Allowed values: "Adams", "Allen", "Bartholomew", "Benton", "Blackford", "Boone", "Brown", "Carrol", "Cass", "Clark", "Clay", "Clinton", "Crawford", "Daviess", "Dearborn", "Decatur", "DeKalb", "Delaware", "Dubois", "Elkhart", "Fayette", "Floyd", "Fountain", "Franklin", "Fulton", "Gibson", "Grant", "Greene", "Hamilton", "Hancock", "Harrison", "Hendricks", "Henry", "Howard", "Huntington", "Jackson", "Jasper", "Jay", "Jefferson", "Jennings", "Johnson", "Knox", "Kosciusko", "LaGrange", "Lake", "LaPorte", "Lawrence", "Madison", "Marion", "Marshall", "Martin", "Miami", "Monroe", "Montgomery", "Morgan", "Newton", "Noble", "Ohio", "Orange", "Owen", "Parke", "Perry", "Pike", "Porter", "Posey", "Pulaski", "Putnam", "Randolph", "Ripley", "Rush", "St.Joseph", "Scott", "Shelby", "Spencer", "Starke", "Steuben", "Sullivan", "Switzerland", "Tippecanoe", "Tipton", "Union", "Vanderburgh", "Vermillion", "Vigo", "Wabash", "Warren", "Warrick", "Washington", "Wayne", "Wells", "White", "Whitley"
SchoolDistrictNum	string	Enter the School District Number if the "TaxTypeCd" is "E" - School District Income Tax.
EmployeeStateSpecificData	object	Contains employee specific data for the selected states.
KS	object	Contains employee state specific data for Kansas.
EmployeeContribution	number	Enter the amount of Employee Contribution to KPERS, KP & F and Judges. Size Range: 0-999999999.99
ME	object	Contains employee state specific data for Maine.
MEPERScontribution	number	Enter the amount of pick-up contributions deducted from this employee’s salary and contributed to MEPERS on behalf of the employee. Size Range: 0-999999999.99
MD	object	Contains employee state specific data for Maryland.
W4ExemptionCount	int	Enter the number of exemptions claimed on Form W-4.
NJ	object	Contains employee state specific data for New Jersey.
PvtFmlLeaveInsuranceNum	string	Enter the Private Family Leave Insurance Plan Number. Size Range: ..14
FmlLeaveInsuranceWH	number	Enter the amount withheld as Family Leave Insurance workers contributions. Size Range: 0-999.99
PvtDisabilityPlanNum	string	Enter the Private Disability Plan Number. Size Range: ..14
DisabilityInsuranceWH	number	Enter the amount withheld as workers’ contributions for Disability Insurance. Size Range: 0-999.99
CombNJUnempInsWrkFrceDevProgHCSubWH	number	Enter the amount withheld as workers contributions for Combined NJ unemployment insurance, Workforce Development Program and health Care Subsidy. Size Range: 0-999.99
DeffCompAmt	number	Enter the total employee elective deferrals to a Code Section 401(k) plan, made during the year. Size Range: 0-9999999.99
IsRetirementPlan	Boolean	When TRUE, identifies that the employee was an active participant (for any part of the year) in a retirement plan.
OR	object	Contains employee state specific data for Oregon.
DateFirstEmployed	date	Enter the date first employed.
DateOfSeparation	date	Enter the date of separation.
TaxableWagesForStateTransitTax	number	Enter the State Taxable Wages for Statewide Transit Tax. Size Range: 0-999999999.99
StateTransitTaxWH	number	Enter the Statewide Transit Tax Withheld. Size Range: 0-999999999.99
MA	object	Contains employee state specific data for Massachusetts.
EeContributionMAPFML	number	Enter the Employee contribution for Paid Family and Medical Leave. Size Range: 0-999999999.99
StateReconData	object	Collects State Recon fields specific for each state. Click here, for the description of each state specific Recon fields.

Response Body

Field	Type	Description
StatusCode	number	Returns the HTTP status codes like 200,300 etc.
StatusName	string	Name of the status code
StatusMessage	string	Detailed status message
Errors	object[]	Shows detailed error information
Id	string	Returns the validation error id
Name	string	Name of the validation error
Message	string	Description of the validation error

Request JSON

{
"SubmissionManifest": {
"SubmissionId": null,
"TaxYear": "2021",
"IsFederalFiling": true,
"IsStateFiling": true,
"IsPostal": false,
"IsOnlineAccess": true,
"IsScheduleFiling": false,
"ScheduleFiling": null
},
"ReturnHeader": {
"Business": {
  "BusinessId": null,
  "BusinessNm": "Brian LLC",
  "TradeNm": "Brian Corporate Services",
  "IsEIN": true,
  "EINorSSN": "991111211",
  "Email": "brianscott@gmail.com",
  "ContactNm": "Brian O Relly",
  "Phone": "1234447890",
  "PhoneExtn": "12345",
  "Fax": "4567893120",
  "BusinessType": "ESTE",
  "SigningAuthority": {
    "Name": "Altof",
    "Phone": "1234578960",
    "BusinessMemberType": "ADMINISTRATOR"
  },
  "KindOfEmployer": "FEDERALGOVT",
  "KindOfPayer": "REGULAR941",
  "IsBusinessTerminated": true,
  "IsForeign": false,
  "USAddress": {
           "Address1": "1751 Kinsey Rd",
           "Address2": "Main St",
           "City": "Dothan",
           "State": "AL",
           "ZipCd": "36303"
         },
  "ForeignAddress": {
    "Address1": "500 Penn Avenue",
    "Address2": "Park Street",
    "City": "Toronto",
    "ProvinceOrStateNm": "Ontario",
    "Country": "CA",
    "PostalCd": "02452"
  }
}
},
"ReturnData": [
{
  "SequenceId": "001",
  "Employee": {
    "SSN": "112-23-6003",
    "FirstNm": "Michael",
    "MiddleNm": "John",
    "LastNm": "Augustin",
    "Suffix": "Sr",
    "Email": "mike@gmail.com",
    "Fax": "4567891234",
    "Phone": "4259631478",
    "IsForeign": false,
    "USAddress": {
           "Address1": "1751 Kinsey Rd",
           "Address2": "Main St",
           "City": "Dothan",
           "State": "AL",
           "ZipCd": "36303"
         },
    "ForeignAddress": {
      "Address1": "500 Penn Avenue",
      "Address2": "Park Street",
      "City": "Toronto",
      "ProvinceOrStateNm": "Ontario",
      "Country": "CA",
      "PostalCd": "02452"
    }
  },
  "W2FormData": {
    "B1Wages": 50000.65,
    "B2FedTaxWH": 5263.32,
    "B3SocSecWages": 137000.00,
    "B4SocSecTaxWH": 46.15,
    "B5MediWages": 137700.00,
    "B6MediTaxWH": 78.21,
    "B7SocSecTips": 700,
    "B8AllocatedTips": 45,
    "B10DependtCareBenefits": 78,
    "B11Sec457Plan": 96,
    "B11NonSec457Plan": 0,
    "B12aCd": "EE",
    "B12aAmt":32,
    "B12bCd": "B",
    "B12bAmt": 21,
    "B12cCd": "E",
    "B12cAmt": 213,
    "B12dCd": "H",
    "B12dAmt": 210,
    "B13IsStatEmp": true,
    "B13IsRetPlan": true,
    "B13Is3rdPartySickPay": true,
    "B14Other": "Real Estate 4500",
    "ControlNum": "35231",
    "States": [
      {
        "B15StateCd": "DE",
        "B15StateIdNum": "9-999999999-123",
        "B16StateWages": 50000.65,
        "B17StateTax": 5263.32,
        "LocalityData": [
          {
            "LocalWages": 300.23,
            "LocalTax": 100.45,
            "LocalityNm": "Pristine"
          }
        ]
      },
      {
        "B15StateCd": "SC",
        "B15StateIdNum": "123456789",
        "B16StateWages": 50000.65,
        "B17StateTax": 5263.32,
        "LocalityData":null
      }
    ]
  }
}
]
}

Response JSON

 {
 "StatusCode": 200,
 "StatusName": "Ok",
 "StatusMessage": "Successful API call",
 "Errors": null
}

1
2
3
4
5
6

← Form943 FormW2C →