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 Params
| 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. Allowed values: "2022","2023","2024" |
| 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 | Enter a date from which the W-2 records need to be listed in MM/DD/YYYY format. |
| ToDate | string | Enter a date till which the w-2 records created are to be listed in MM/DD/YYYY format. |
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 Form W-2 records with Success and Error statuses |
| 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. |
| PayeeRef | string | A unique identifier for each payee completing their information. |
| EmployeeName | Boolean | Name of the employee. |
| FirstNm | string | First Name of the Individual |
| MiddleNm | string | Middle Name of the Individual |
| LastNm | string | Last Name of the Individual |
| Suffix | string | Suffix of the Individual |
| 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. |
| 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 |
| 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. |
| string | Email address for whom the online access to be given. | |
| Info | string | Information about the online access service. |
| 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 Params
- Node.js
- Python
- Java
- .NET C#
"Formw2/List?BusinessId=417be5c4-0a9a-46f1-ba41-69c39f3a90de"
Response Json
| Response | Description | Action |
|---|---|---|
| 200 | Success Response - This is a sample response for successful API requests. |
Response: 200
{
"StatusCode": 200,
"StatusName": "Ok",
"StatusMessage": "Successful API call",
"FormW2Records": [
{
"SubmissionId": "b1c1fca0-41d4-4be1-bfd4-3b6756c22790",
"BusinessId": "417be5c4-0a9a-46f1-ba41-69c39f3a90de",
"PayerRef": "379946",
"BusinessNm": "Snowdaze LLC",
"EIN": "52-6672586",
"ContactName": "Chandler White",
"TaxYear": "2024",
"Employee": {
"SequenceId": "01",
"RecordId": "065d46f2-4b5e-49e6-a62a-4c9d2f2f0515",
"EmployeeId": "60f86bf9-a55a-4055-9eda-d7659b3c1b2b",
"PayeeRef": "Payee001",
"EmployeeName": "Mark Freek Linda Sr",
"FirstNm": "Mark",
"LastNm": "Linda",
"MiddleNm": "Freek",
"Suffix": "Sr",
"SSN": "266-87-3255",
"FederalReturn": {
"Status": "CREATED",
"StatusTs": "2024-06-29 03:42:26 -04:00",
"Info": null,
"Errors": null
},
"StateReturns": [
{
"StateCd": "DE",
"Status": "CREATED",
"StatusTs": "2024-06-29 03:32:31 -04:00",
"Info": null,
"Errors": null
},
{
"StateCd": "SC",
"Status": "CREATED",
"StatusTs": "2024-06-29 03:32:31 -04:00",
"Info": "You should take care of filing Form WH-1606, Fourth Quarter/Annual Withholding Tax Reconciliation Report, with the state of South Carolina. The due date to file Form WH-1606 is January 31,2024. https://dor.sc.gov/forms-site/Forms/WH1606.pdf",
"Errors": null
}
],
"Postal": {
"Status": "CREATED",
"StatusTs": "2024-06-29 03:42:26 -04:00",
"Info": null
},
"OnlineAccess": {
"Status": "CREATED",
"Email": "mark+13@sample.com",
"Info": null
}
}
},
{
"SubmissionId": "fbf4d042-0a23-42ba-9779-f9e30c4c20a4",
"BusinessId": "417be5c4-0a9a-46f1-ba41-69c39f3a90de",
"PayerRef": "379946",
"BusinessNm": "Snowdaze LLC",
"EIN": "52-6672486",
"ContactName": "Chandler White",
"TaxYear": "2024",
"Employee": {
"SequenceId": "01",
"RecordId": "a3c92259-e296-4147-8649-26ef7a68890c",
"EmployeeId": "ca383c44-22d1-4765-82de-1319b07fdba7",
"PayeeRef": "Payee002",
"EmployeeName": "Mark Freek Linda Sr",
"FirstNm": "Mark",
"LastNm": "Linda",
"MiddleNm": "Freek",
"Suffix": "Sr",
"SSN": "266-87-3245",
"FederalReturn": {
"Status": "CREATED",
"StatusTs": "2024-06-29 03:32:31 -04:00",
"Info": null,
"Errors": null
},
"StateReturns": [
{
"StateCd": "DE",
"Status": "CREATED",
"StatusTs": "2024-06-29 03:32:31 -04:00",
"Info": null,
"Errors": null
},
{
"StateCd": "SC",
"Status": "CREATED",
"StatusTs": "2024-06-29 03:32:31 -04:00",
"Info": "You should take care of filing Form WH-1606, Fourth Quarter/Annual Withholding Tax Reconciliation Report, with the state of South Carolina. The due date to file Form WH-1606 is January 31,2024. https://dor.sc.gov/forms-site/Forms/WH1606.pdf",
"Errors": null
}
],
"Postal": {
"Status": "CREATED",
"StatusTs": "2024-06-29 03:32:31 -04:00",
"Info": null
},
"OnlineAccess": {
"Status": "CREATED",
"Email": "mark+123@sample.com",
"Info": null
}
}
}
],
"TotalRecords": 2,
"TotalPages": 1,
"Page": 1,
"PageSize": 100,
"Errors": null
}