Status

Status

This endpoint can be used to retrieve the status of W-2 returns transmitted via the TaxBandits API. Provide the SubmissionId and RecordId, and the response will return the status of federal filing, state filing, postal mailing, and online access.

Federal Filing

• CREATED - The form has been created but not yet transmitted.
• TRANSMITTED - The form has been transmitted by the user.
• SENT_TO_AGENCY - The form has been sent to the SSA, and a result is pending.
• ACCEPTED - The form has been accepted by the SSA.
• REJECTED - The form has been rejected by the SSA due to errors. The user must correct the errors and retransmit.
• YET_TO_RETRANSMIT - The rejected form has been updated and is pending retransmission to the SSA.

State Filing

• CREATED - The form has been created but not yet transmitted.
• NOT_CREATED - The form hasn't been created because state filing wasn't opted for.
• TRANSMITTED - The form has been transmitted by the user.
• SENT_TO_AGENCY - The form has been sent to the state DOR, and a result is pending.
• ACCEPTED - The form has been accepted by the state DOR.
• REJECTED - The form has been rejected by the state DOR.

Postal Mailing

• CREATED - Postal mailing has been opted for.
• SENT - Form copies have been mailed to the employee.
• RECEIVED - Form copies have been received by the employee.
• NOT_CREATED - Postal mailing wasn't opted for. To enable it, set IsPostalMailing to TRUE in the submission manifest of the Create request.

Online Access

• CREATED - Online Access has been opted for; a secure download link will be emailed to the employee once the form is transmitted.
• ORDER_CREATED - Online Access has been opted for; a secure download link will be emailed to the employee once the form is transmitted.Be sent shortly.
• EMAIL_SENT - A secure link to download the form has been emailed to the employee.
• VIEWED_FORM - The employee has viewed the form.
• DOWNLOADED_FORM - The employee has viewed and downloaded the form.

GET FormW2/Status 

Run in Postman

Request Body

Field	Type	Description
SubmissionId	Guid	A unique identifier of a submission.
RecordIds	Guid	A unique identifier generated by TaxBandits when a return's is created. Mention the return RecordId for which you want to get the status.

Response Body

Field	Type	Description
SubmissionId	Guid	Unique identifier generated for the submission.
FormType	string	Denotes the type of the form.
FormW2Records	object[]	Returns the status of processed records along with their federal, state, and distribution statuses.
RecordId	Guid	Unique identifier generated for the submitted tax form record.
FederalStatus	object	Returns the federal filing status details for the record.
Code	string	Status code representing the federal filing result.
Status	string	Current status of the federal filing (for example, ACCEPTED, REJECTED).
Message	string	Detailed description of the federal filing status.
StatusTs	string	Date and time when the federal filing status was last updated.
StateStatus	object	Returns the filing status details for each state where the return was filed.
StateCd	string	Two-letter state code for the filing jurisdiction.
Code	string	Status code representing the state filing result.
Status	string	Current filing status for the specified state.
Message	string	Detailed description of the state filing status.
StatusTs	string	Date and time when the state filing status was last updated.
Distribution	object	Returns the distribution details for the employee copy of the form.
DistributionType	string	Specifies the distribution method used to deliver the employee copy (for example, POSTAL_AND_ONLINE).
PostalStatus	object	Returns the postal delivery status information.
PostalType	string	Specifies the postal delivery service used (for example, USPS_FIRST_CLASS).
Code	string	Status code representing the postal delivery status.
Status	string	Current postal delivery status (for example, ASSUMED_DELIVERED, IN_TRANSIT).
Message	string	Detailed description of the postal delivery status.
StatusTs	string	Date and time when the postal delivery status was last updated.
OnlineAccessStatus	object	Returns the online access status information for the employee.
Email	string	Email address provided for employee online access.
Code	string	Status code representing the online access status.
Status	string	Current status of online access (for example, VIEWED_FORM, EMAIL_SENT).
Message	string	Detailed description of the online access status.
StatusTs	string	Date and time when the online access status was last updated.
Errors	object[]	Returns top-level validation or processing errors. Returns null when the request is processed successfully.
Id	string	Validation or processing error code.
Name	string	Name of the field or validation rule that caused the error.
Message	string	Detailed description of the error and guidance for resolving it.
ErrorRecords	object[]	It will show the detailed information about the error status of the Form 1099-NEC Records.
SequenceId	string	A unique reference ID for the submission that can be used to identify a particular record. The SequenceId will be returned in the response for your reference.
RecordId	Guid	A 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.

Payload

Request Params

Sample	Description	Action
Sample 1	Query Params - Get status using SubmissionId and RecordIds.

Sample 1

formw2/status?submissionId=f47ac10b-58cc-4372-a567-0e02b2c3d479&recordIds=cfd6fe66-ac9f-49f7-b8a3-2d064abeeb9b

Response JSON

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

Response: 200

{
  "SubmissionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "FormType": "FormW2",
  "FormW2Records": [
    {
      "RecordId": "cfd6fe66-ac9f-49f7-b8a3-2d064abeeb9b",
      "FederalStatus": {
        "Code": "FED-002",
        "Status": "ACCEPTED",
        "Message": "Accepted by IRS",
        "StatusTs": "2026-01-25T11:42:00-05:00"
      },
      "StateStatus": [
        {
          "StateCd": "AZ",
          "Code": "ST-001",
          "Status": "ACCEPTED",
          "Message": "Accepted by AZ",
          "StatusTs": "2026-01-25T11:43:00-05:00"
        }
      ],
      "Distribution": {
        "DistributionType": "POSTAL_AND_ONLINE",
        "PostalStatus": {
          "PostalType": "USPS_FIRST_CLASS",
          "Code": "POS-006",
          "Status": "DELIVERED",
          "Message": "Stamped delivered by USPS",
          "StatusTs": "2026-01-30T16:00:00-05:00"
        },
        "OnlineAccessStatus": {
          "Email": "shawn@sample.com",
          "Code": "OA-004",
          "Status": "VIEWED_FORM",
          "Message": "Recipient viewed the form",
          "StatusTs": "2026-01-25T15:00:00-05:00"
        }
      }
    }
  ],
  "Errors": null
}

Go Lang

package main

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

func main() {
  url := "<APIURL>/v2.0.0/FormW2/status?submissionId=f47ac10b-58cc-4372-a567-0e02b2c3d479&recordIds=cfd6fe66-ac9f-49f7-b8a3-2d064abeeb9b"
  method := "GET"

  // GET request does not require a request body
  req, err := http.NewRequest(method, url, nil)
  if err != nil {
    fmt.Println(err)
    return
  }

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

  client := &http.Client{}

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

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

  fmt.Println(string(body))
}

Node.js

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

let config = {
  method: 'get',
  maxBodyLength: Infinity,
  url: '<APIURL>/v2.0.0/formw2/status?submissionId=f47ac10b-58cc-4372-a567-0e02b2c3d479&recordIds=cfd6fe66-ac9f-49f7-b8a3-2d064abeeb9b',
  headers: { 
    'Content-Type': 'application/json', 
    'Authorization': '<ACCESS_TOKEN>'
  },
  data : data
};

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

Python

import http.client
import json

conn = http.client.HTTPSConnection("<APIURL>")
payload = ''
headers = {
  'Content-Type': 'application/json',
  'Authorization': '<ACCESS_TOKEN>'
}
conn.request("GET", "/v2.0.0/formw2/status?submissionId=f47ac10b-58cc-4372-a567-0e02b2c3d479&recordIds=cfd6fe66-ac9f-49f7-b8a3-2d064abeeb9b", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

.NET C#

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Get, "<APIURL>/v2.0.0/formw2/status?submissionId=f47ac10b-58cc-4372-a567-0e02b2c3d479&recordIds=cfd6fe66-ac9f-49f7-b8a3-2d064abeeb9b");
request.Headers.Add("Authorization", "<ACCESS_TOKEN>");
var content = new StringContent("", null, "application/json");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

Ruby

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

url = URI("<APIURL>/v2.0.0/formw2/status?submissionId=f47ac10b-58cc-4372-a567-0e02b2c3d479&recordIds=cfd6fe66-ac9f-49f7-b8a3-2d064abeeb9b")

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

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

Java

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
  .url("<APIURL>/v2.0.0/formw2/status?submissionId=f47ac10b-58cc-4372-a567-0e02b2c3d479&recordIds=cfd6fe66-ac9f-49f7-b8a3-2d064abeeb9b")
  .method("GET", body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Authorization", "<ACCESS_TOKEN>")
  .build();
Response response = client.newCall(request).execute();

cURL

curl --location '<APIURL>/v2.0.0/formw2/status?submissionId=f47ac10b-58cc-4372-a567-0e02b2c3d479&recordIds=cfd6fe66-ac9f-49f7-b8a3-2d064abeeb9b' --header 'Content-Type: application/json' --header 'Authorization: <ACCESS_TOKEN>' --data ''