Status
This method will return the current status of the Form W-2 for a particular submission or for a particular employee.
Federal
- CREATED - Form W-2 has been created and has not yet been transmitted.
- TRANSMITTED - Form W-2 has been transmitted by the user.
- SENT TO AGENCY - Form W-2 has been sent to the SSA, and we are waiting for the result from the IRS.
- ACCEPTED - Form W-2 is accepted by the SSA.
- REJECTED - Form W-2 is rejected by the SSA due to some errors. The user must correct the errors and retransmit the forms.
State
- CREATED - Form W-2 (State) has been created and has not yet been transmitted.
- NOTCREATED - Form W-2 (State) has not been created since state filing hasn't been opted.
- TRANSMITTED - Form W-2 (State) has been transmitted by the user.
- SENT TO AGENCY - Form W-2 (State) has been sent to the state DOR, and we are waiting for the result.
- ACCEPTED - Form W-2 is accepted by the state DOR.
- REJECTED - Form W-2 is rejected by the state DOR.
- CANCELLED - Form W-2 (State) was canceled and will not be processed.
Postal Mailing
- CREATED - Postal mailing opted for the W-2 Forms.
- SENT - Form copies are mailed to the employees.
- RECEIVED - Form copies are received by the employees.
- NOTCREATED - Postal mailing wasn't opted. To opt for postal mailing, the 'IsPostalMailing' in the submission manifest of the Create request must be set to TRUE.
Online Access
- CREATED - Online Access opted for the W-2 forms, and the secure link to download form copies will be emailed to the employees as soon as the form is transmitted.
- ORDER_RECEIVED - An order for online access has been received and the email will be sent to the recipient soon.
- EMAIL_SENT - A secure link to download form copies has been emailed to the employees.
- DOWNLOADED_FORM - The employee successfully viewed and downloaded the form.
- VIEWED_FORM - The employee has successfully viewed the form.
GET FormW2/Status 
Request Params
| Field | Type | Description |
|---|---|---|
| SubmissionId | Guid | Mention the W2 returns Submission ID that you want to get the status. |
| RecordIds | Guid | Mention the W2 returns Record ID that you want to get status. Multiple RecordIds status’ under the same Submission can be known by sending the RecordIds comma separated. |
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. |
| PayeeRef | string | A unique identifier for each payee completing their information. |
| 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. |
| 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 Params
- Node.js
- Python
- Java
- .NET C#
Request Params
| Sample | Description | Action |
|---|---|---|
| Sample 1 | Get status with only the SubmissionID | |
| Sample 2 | Get status with SubmissionID and 2 RecordIDs |
Sample 1
"FormW2/Status?SubmissionId=fbf4d042-0a23-42ba-9779-f9e30c4c20a4"
Response Json
| Sample | Description | Action |
|---|---|---|
| 200 | Success Response - This is a sample response for successful API requests. | |
| 300 | Multi-status Response - You'll get the below response when multiple statuses are included. | |
| 404 | Not Found Response - You'll get the below response if your API request contains a record that's not found in our database. |
Response: 200
{
"StatusCode": 200,
"StatusName": "Ok",
"StatusMessage": "Successful API call",
"SubmissionId": "a1fd86fb-e404-442d-ae37-c5f6d1a1cc14",
"BusinessId": "e097c642-f1cf-48b0-88fc-01c1197647c3",
"PayerRef": "Snow123",
"FormW2Records": {
"SuccessRecords": [
{
"SequenceId": "1",
"RecordId": "2d9309cd-5b5b-42bf-b68a-c237c9b2c67e",
"EmployeeId": "1325f550-cc2b-484a-8173-83ffb805e6cf",
"PayeeRef": "Payee001",
"FederalReturn": {
"Status": "TRANSMITTED",
"StatusTs": "2024-06-05 06:54:28 -04:00",
"Info": null,
"Errors": null
},
"StateReturns": [
{
"StateCd": "WV",
"Status": "TRANSMITTED",
"StatusTs": "2024-06-05 06:54:34 -04:00",
"Info": null,
"Errors": null
}
],
"Postal": {
"Status": "CREATED",
"StatusTs": "2024-06-05 06:54:28 -04:00",
"Info": null
},
"OnlineAccess": {
"Status": "EMAIL_SENT",
"Email": "shawn@sample.com",
"Info": null
},
"ScheduleFiling": {
"ScheduledOn": null,
"Info": "This service will be available soon"
}
},
{
"SequenceId": "2",
"RecordId": "bd312551-60fe-4775-a8e3-a48acc96899b",
"EmployeeId": "1325f550-cc2b-484a-8173-83ffb805e6cf",
"PayeeRef": "Payee002",
"FederalReturn": {
"Status": "SENT TO AGENCY",
"StatusTs": "2024-06-05 06:55:08 -04:00",
"Info": null,
"Errors": null
},
"StateReturns": [
{
"StateCd": "WV",
"Status": "SENT TO AGENCY",
"StatusTs": "2024-06-05 06:54:34 -04:00",
"Info": null,
"Errors": null
}
],
"Postal": {
"Status": "CREATED",
"StatusTs": "2024-06-05 06:56:04 -04:00",
"Info": null
},
"OnlineAccess": {
"Status": "EMAIL_SENT",
"Email": "shawn@sample.com",
"Info": null
},
"ScheduleFiling": {
"ScheduledOn": null,
"Info": "This service will be available soon"
}
},
{
"SequenceId": "3",
"RecordId": "a051a093-2d40-4bdd-80a7-c102b489da38",
"EmployeeId": "1325f550-cc2b-484a-8173-83ffb805e6cf",
"PayeeRef": "Payee003",
"FederalReturn": {
"Status": "ACCEPTED",
"StatusTs": "2024-06-05 06:55:16 -04:00",
"Info": null,
"Errors": null
},
"StateReturns": [
{
"StateCd": "WV",
"Status": "ACCEPTED",
"StatusTs": "2024-06-05 06:54:34 -04:00",
"Info": null,
"Errors": null
}
],
"Postal": {
"Status": "CREATED",
"StatusTs": "2024-06-05 06:56:13 -04:00",
"Info": null
},
"OnlineAccess": {
"Status": "EMAIL_SENT",
"Email": "shawn@sample.com",
"Info": null
},
"ScheduleFiling": {
"ScheduledOn": null,
"Info": "This service will be available soon"
}
},
{
"SequenceId": "4",
"RecordId": "124355cd-b7ed-4103-8214-1b7f78980f74",
"EmployeeId": "1325f550-cc2b-484a-8173-83ffb805e6cf",
"PayeeRef": "Payee004",
"FederalReturn": {
"Status": "REJECTED",
"StatusTs": "2024-06-05 06:55:16 -04:00",
"Info": null,
"Errors": [
{
"Id": "F68-FED-10001",
"Name": "Rejected Record",
"Message": "Sample Error Message"
}
]
},
"StateReturns": [
{
"StateCd": "WV",
"Status": "REJECTED",
"StatusTs": "2024-06-05 06:54:34 -04:00",
"Info": null,
"Errors": null
}
],
"Postal": {
"Status": "CREATED",
"StatusTs": "2024-06-05 06:56:13 -04:00",
"Info": null
},
"OnlineAccess": {
"Status": "EMAIL_SENT",
"Email": "shawn@sample.com",
"Info": null
},
"ScheduleFiling": {
"ScheduledOn": null,
"Info": "This service will be available soon"
}
}
],
"ErrorRecords": null
},
"Errors": null
}