Version: 2.0.0

List

This endpoint retrieves a list of Form W-2 returns that have been created, submitted, or transmitted in TaxBandits, filtered by submission or business identifiers. For example, passing a BusinessId returns all returns created under that business.

You can also filter results by status type (Federal Filing, State Filing, Online Access, or Postal Mailing) and retrieve returns with a specific status (e.g., Accepted, Rejected, Pending).

POST formw2/list

Run in Postman

Request Body

Field	Type	Description
TaxYear	string	Tax year for which the W-2 returns should be listed.
FormTypes	Object[]	List of form types to filter the returns. Allowed values Allowed values Allowed Values: "FORMW2"
Business	object	Business details used to identify the payer.
BusinessId	GUID	Unique Business ID generated by TaxBandits. If provided, you do not need to send the business details again.
PayerRef	String	Optional Your unique reference for the payer. Can be used instead of BusinessId. Size Range: 50
BusinessNm	String	Legal name of the business. Size Range: 75
TINType	String	TIN type of the business. Allowed values Allowed values Allowed Values: "EIN"
PayerTIN	String	Last four digits of the business TIN.
Employee	object	Employee details used to identify the Employee.
EmployeeId	GUID	Unique Employee ID generated by TaxBandits.
EmployeeRef	String	Optional Your unique reference for the Employee. Size Range: 50
EmployeeNm	String	Name of the Employee. Size Range: 75
EmployeeTINType	String	TIN type of the Employee. Allowed values Allowed values Allowed Values: "SSN"
EmployeeLast4TIN	String	Last four digits of the Employee's TIN.
SubmissionId	GUID	Unique ID assigned by TaxBandits to the submission.
Federal	object	Filters returns based on the federal filing status.
Status	Object[]	One or more federal return statuses to filter the results. Allowed values Allowed values Allowed Values: "CREATED", "TRANSMITTED", "SENT TO AGENCY", "ACCEPTED", "REJECTED"
State	object	Filters returns based on the state filing status.
Status	Object[]	One or more state return statuses to filter the results. Allowed values Allowed values Allowed Values: "CREATED", "NOTCREATED", "TRANSMITTED", "SENTTOAGENCY", "ACCEPTED", "REJECTED"
Distribution	object	Filters returns based on online access or postal distribution status.
OAStatus	Object[]	One or more online access statuses to filter the results. Allowed values Allowed values Allowed Values: "CREATED", "ORDER_CREATED", "EMAIL_SENT", "DOWNLOADED_FORM", "VIEWED_FORM"
PostalStatus	Object[]	One or more postal distribution statuses to filter the results. Allowed Values: "CREATED", "SENT", "RECEIVED", "NOTCREATED"
FromDate	string	Start date for listing returns (MM/DD/YYYY).
ToDate	string	End date for listing returns (MM/DD/YYYY).
Page	Number	Page number of the results to retrieve.
PageSize	Number	Number of records to return per page (maximum 100).
Errors	object[]	List of validation errors for state returns.
Id	string	Unique ID of the validation error.
Name	string	Name of the validation error.
Message	string	Description of the validation error.

Response Body

Field	Type	Description
FormW2EmployeeRecords	Object[]	List of W-2 return records.
TaxYear	string	Tax year of the listed returns.
FormType	string	Form type of the listed W-2 returns.
SubmissionId	GUID	Unique ID of the submission.
RecordId	GUID	Unique ID of the return record.
BusinessId	GUID	Unique ID of the business.
BusinessNm	string	Name of the business.
PayerRef	string	Your unique reference for the business.
EmployeeId	GUID	Unique ID of the Employee.
EmployeeRef	string	Your unique reference for the Employee.
IndividualNm	string	Returns name of the Employee.
FirstNm	String	First name of the Employee.
MiddleNm	String	Middle name of the Employee.
LastNm	String	Last name of the Employee.
Suffix	String	Suffix of the Employee's name
FederalStatus	object	Federal filing status details for the return.
Status	string	Current status of the return.
Info	string	Additional information about the federal filing service.
StatusTs	string	Date and time when the federal status was updated.
StatesStatus	object	State filing status details for the return.
Status	string	Current state filing status.
Info	string	Additional information about the state filing service.
StatusTs	string	Date and time the state status was updated.
Distribution	object	Distribution status details for postal or online access.
DistributionType	string	Distribution method selected for the return.
PostalStatus	object	Postal mailing status details.
PostalType	String	Postal mailing method selected for the return.
Status	String	Current postal mailing status.
Info	String	Additional information about the postal mailing service.
StatusTs	String	Date and time when the return was processed for postal mailing.
OnlineAccessStatus	Object	Online access status details.
Email	String	Email address used for online access.
Status	String	Current online access status.
Info	String	Additional information about the online access service.
StatusTs	String	Date and time when the return was processed for online access.
AttachmentURL	String	URL to download the PDF of any additional attachments.
CreatedTs	String	Date and time when the return was created.
LastUpdatedTs	String	Date and time when the return was last updated.
Page	number	Page number containing the listed records.
PageSize	number	Number of records returned per page.
Errors	object[]	Error details if validation errors.
Id	string	Unique ID of the validation error.
Name	string	Name of the validation error.
Message	string	Description of the validation error.

Request Json

Sample	Description	Action
Sample 1	List Form W2 returns using payer, submission, filing status, state status, and distribution filters.

Sample 1

{
  "TaxYear": "2026",
  "FormTypes": [
    "FORMW2"
  ],
  "Business": {
    "BusinessId": null,
    "PayerRef": "Payer132",
    "BusinessNm": "Steven LLC",
    "TINType": "EIN",
    "PayerTIN": null
  },
  "Employee": {
    "EmployeeId": null,
    "EmployeeRef": "Payee123",
    "EmployeeNm": null,
    "EmployeeTINType": "SSN",
    "EmployeeLast4TIN": null
  },
  "SubmissionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "Federal": {
    "Status": [
      "CREATED",
      "TRANSMITTED",
      "SCHEDULED"
    ]
  },
  "State": {
    "StateCd": [
      "SC",
      "MD"
    ],
    "Status": [
      "CREATED",
      "SCHEDULED "
    ]
  },
  "Distribution": {
    "OAStatus": [
      "OPENED",
      "VIEWED"
    ],
    "PostalStatus": [
      "SENT"
    ]
  },
  "FromDate": null,
  "ToDate": null,
  "Page": 1,
  "PageSize": 100
}

Response JSON

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

Response: 200

{
  "FormW2EmployeeRecords": [
    {
      "TaxYear": "2026",
      "FormType": "FormW2",
      "SubmissionId": "e50c27b8-631c-45f0-be19-f786fc69ba60",
      "RecordId": "cfd6fe66-ac9f-49f7-b8a3-2d064abeeb9b",
      "BusinessId": "bbd57dc2-d948-40cd-b67b-9fe06cc62218",
      "BusinessNm": "",
      "PayerRef": "Snow123",
      "EmployeeId": "4fb305b7-f0d7-4093-9152-93f07313b606",
      "EmployeeRef": "DAI001",
      "IndividualNm": {
        "FirstNm": "Tim",
        "MiddleNm": null,
        "LastNm": "Jude",
        "Suffix": null
      },
      "FederalStatus": {
        "StatusCd": "FED-002",
        "Status": "TRANSMITTED",
        "Info": "Transmitted to SSA",
        "StatusTs": "2026-01-25T09:00:00-05:00"
      },
      "StatesStatus": [
        {
          "StateCd": "AZ",
          "StatusCd": "ST-002",
          "Status": "TRANSMITTED",
          "Info": "Transmitted to AZ",
          "StatusTs": "2026-01-25T09:01:12-05:00"
        }
      ],
      "Distribution": {
        "DistributionType": "POSTAL_AND_ONLINE",
        "PostalStatus": {
          "PostalType": "USPS_FIRST_CLASS",
          "Code": "POS-004",
          "Status": "HANDED_OVER_TO_USPS",
          "Info": "Handed off to USPS",
          "StatusTs": "2026-01-26T14:30:00-05:00"
        },
        "OnlineAccessStatus": {
          "Email": "shawn@sample.com",
          "Code": "OA-003",
          "Status": "EMAIL_SENT",
          "Info": "Notification email sent",
          "StatusTs": "2026-01-25T09:05:00-05:00"
        }
      },
      "AttachmentURL": "https://amazonaws.com/pdfs/a570efbd-740f-4ae2-bfe7-26356cd85148.pdf",
      "CreatedTs": "2026-01-02T02:17:04-05:00",
      "LastUpdatedTs": "2026-01-26T14:30:00-05:00"
    }
  ],
  "Page": 1,
  "PageSize": 100,
  "TotalRecords": 1,
  "TotalPages": 1,
  "Errors": null
}

package main

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

func main() {
  url := "<APIURL>/v2.0.0/formw2/list"
  method := "POST"

  payload := strings.NewReader(`{
    "TaxYear": "2026",
    "FormTypes": [
      "FORMW2"
    ],
    "Business": {
      "BusinessId": null,
      "PayerRef": "Payer132",
      "BusinessNm": "Steven LLC",
      "TINType": "EIN",
      "PayerTIN": null
    },
    "Employee": {
      "EmployeeId": null,
      "EmployeeRef": "Payee123",
      "EmployeeNm": null,
      "EmployeeTINType": "SSN",
      "EmployeeLast4TIN": null
    },
    "SubmissionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "Federal": {
      "Status": [
        "CREATED",
        "TRANSMITTED",
        "SCHEDULED"
      ]
    },
    "State": {
      "StateCd": [
        "SC",
        "MD"
      ],
      "Status": [
        "CREATED",
        "SCHEDULED "
      ]
    },
    "Distribution": {
      "OAStatus": [
        "OPENED",
        "VIEWED"
      ],
      "PostalStatus": [
        "SENT"
      ]
    },
    "FromDate": null,
    "ToDate": null,
    "Page": 1,
    "PageSize": 100
  }`)

  client := &http.Client{}

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

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

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

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

  fmt.Println(string(body))
}

const axios = require('axios');
let data = JSON.stringify({
  "TaxYear": "2026",
  "FormTypes": [
    "FORMW2"
  ],
  "Business": {
    "BusinessId": null,
    "PayerRef": "Payer132",
    "BusinessNm": "Steven LLC",
    "TINType": "EIN",
    "PayerTIN": null
  },
  "Employee": {
    "EmployeeId": null,
    "EmployeeRef": "Payee123",
    "EmployeeNm": null,
    "EmployeeTINType": "SSN",
    "EmployeeLast4TIN": null
  },
  "SubmissionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "Federal": {
    "Status": [
      "CREATED",
      "TRANSMITTED",
      "SCHEDULED"
    ]
  },
  "State": {
    "StateCd": [
      "SC",
      "MD"
    ],
    "Status": [
      "CREATED",
      "SCHEDULED "
    ]
  },
  "Distribution": {
    "OAStatus": [
      "OPENED",
      "VIEWED"
    ],
    "PostalStatus": [
      "SENT"
    ]
  },
  "FromDate": null,
  "ToDate": null,
  "Page": 1,
  "PageSize": 100
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: '<APIURL>/v2.0.0/formw2/list',
  headers: { 
    'Content-Type': 'application/json', 
    'Authorization': '<ACCESS_TOKEN>'
  },
  data : data
};

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

import http.client
import json

conn = http.client.HTTPSConnection("<APIURL>")
payload = json.dumps({
  "TaxYear": "2026",
  "FormTypes": [
    "FORMW2"
  ],
  "Business": {
    "BusinessId": None,
    "PayerRef": "Payer132",
    "BusinessNm": "Steven LLC",
    "TINType": "EIN",
    "PayerTIN": None
  },
  "Employee": {
    "EmployeeId": None,
    "EmployeeRef": "Payee123",
    "EmployeeNm": None,
    "EmployeeTINType": "SSN",
    "EmployeeLast4TIN": None
  },
  "SubmissionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "Federal": {
    "Status": [
      "CREATED",
      "TRANSMITTED",
      "SCHEDULED"
    ]
  },
  "State": {
    "StateCd": [
      "SC",
      "MD"
    ],
    "Status": [
      "CREATED",
      "SCHEDULED "
    ]
  },
  "Distribution": {
    "OAStatus": [
      "OPENED",
      "VIEWED"
    ],
    "PostalStatus": [
      "SENT"
    ]
  },
  "FromDate": None,
  "ToDate": None,
  "Page": 1,
  "PageSize": 100
})
headers = {
  'Content-Type': 'application/json',
  'Authorization': '<ACCESS_TOKEN>'
}
conn.request("POST", "/v2.0.0/formw2/list", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "<APIURL>/v2.0.0/formw2/list");
request.Headers.Add("Authorization", "<ACCESS_TOKEN>");
var content = new StringContent("{
  "TaxYear": "2026",
  "FormTypes": [
    "FORMW2"
  ],
  "Business": {
    "BusinessId": null,
    "PayerRef": "Payer132",
    "BusinessNm": "Steven LLC",
    "TINType": "EIN",
    "PayerTIN": null
  },
  "Employee": {
    "EmployeeId": null,
    "EmployeeRef": "Payee123",
    "EmployeeNm": null,
    "EmployeeTINType": "SSN",
    "EmployeeLast4TIN": null
  },
  "SubmissionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "Federal": {
    "Status": [
      "CREATED",
      "TRANSMITTED",
      "SCHEDULED"
    ]
  },
  "State": {
    "StateCd": [
      "SC",
      "MD"
    ],
    "Status": [
      "CREATED",
      "SCHEDULED "
    ]
  },
  "Distribution": {
    "OAStatus": [
      "OPENED",
      "VIEWED"
    ],
    "PostalStatus": [
      "SENT"
    ]
  },
  "FromDate": null,
  "ToDate": null,
  "Page": 1,
  "PageSize": 100
}", null, "application/json");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

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

url = URI("<APIURL>/v2.0.0/formw2/list")

http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Post.new(url)
request["Content-Type"] = "application/json"
request["Authorization"] = "<ACCESS_TOKEN>"
request.body = JSON.dump({
  "TaxYear": "2026",
  "FormTypes": [
    "FORMW2"
  ],
  "Business": {
    "BusinessId": "nil",
    "PayerRef": "Payer132",
    "BusinessNm": "Steven LLC",
    "TINType": "EIN",
    "PayerTIN": "nil"
  },
  "Employee": {
    "EmployeeId": "nil",
    "EmployeeRef": "Payee123",
    "EmployeeNm": "nil",
    "EmployeeTINType": "SSN",
    "EmployeeLast4TIN": "nil"
  },
  "SubmissionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "Federal": {
    "Status": [
      "CREATED",
      "TRANSMITTED",
      "SCHEDULED"
    ]
  },
  "State": {
    "StateCd": [
      "SC",
      "MD"
    ],
    "Status": [
      "CREATED",
      "SCHEDULED "
    ]
  },
  "Distribution": {
    "OAStatus": [
      "OPENED",
      "VIEWED"
    ],
    "PostalStatus": [
      "SENT"
    ]
  },
  "FromDate": "nil",
  "ToDate": "nil",
  "Page": 1,
  "PageSize": 100
})

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

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{
  "TaxYear": "2026",
  "FormTypes": [
    "FORMW2"
  ],
  "Business": {
    "BusinessId": null,
    "PayerRef": "Payer132",
    "BusinessNm": "Steven LLC",
    "TINType": "EIN",
    "PayerTIN": null
  },
  "Employee": {
    "EmployeeId": null,
    "EmployeeRef": "Payee123",
    "EmployeeNm": null,
    "EmployeeTINType": "SSN",
    "EmployeeLast4TIN": null
  },
  "SubmissionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "Federal": {
    "Status": [
      "CREATED",
      "TRANSMITTED",
      "SCHEDULED"
    ]
  },
  "State": {
    "StateCd": [
      "SC",
      "MD"
    ],
    "Status": [
      "CREATED",
      "SCHEDULED "
    ]
  },
  "Distribution": {
    "OAStatus": [
      "OPENED",
      "VIEWED"
    ],
    "PostalStatus": [
      "SENT"
    ]
  },
  "FromDate": null,
  "ToDate": null,
  "Page": 1,
  "PageSize": 100
}");
Request request = new Request.Builder()
  .url("<APIURL>/v2.0.0/formw2/list")
  .method("POST", body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Authorization", "<ACCESS_TOKEN>")
  .build();
Response response = client.newCall(request).execute();

curl --location '<APIURL>/v2.0.0/formw2/list' --header 'Content-Type: application/json' --header 'Authorization: <ACCESS_TOKEN>' --data '{
  "TaxYear": "2026",
  "FormTypes": [
    "FORMW2"
  ],
  "Business": {
    "BusinessId": null,
    "PayerRef": "Payer132",
    "BusinessNm": "Steven LLC",
    "TINType": "EIN",
    "PayerTIN": null
  },
  "Employee": {
    "EmployeeId": null,
    "EmployeeRef": "Payee123",
    "EmployeeNm": null,
    "EmployeeTINType": "SSN",
    "EmployeeLast4TIN": null
  },
  "SubmissionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "Federal": {
    "Status": [
      "CREATED",
      "TRANSMITTED",
      "SCHEDULED"
    ]
  },
  "State": {
    "StateCd": [
      "SC",
      "MD"
    ],
    "Status": [
      "CREATED",
      "SCHEDULED "
    ]
  },
  "Distribution": {
    "OAStatus": [
      "OPENED",
      "VIEWED"
    ],
    "PostalStatus": [
      "SENT"
    ]
  },
  "FromDate": null,
  "ToDate": null,
  "Page": 1,
  "PageSize": 100
}'

W-9/W-8 Automation

1099 Automation

TIN Matching

W-2 Automation

941/940 Automation

1098-T Automation

ACA Automation

Extension Automation

1042-S Automation

Supported Forms

Gig Software

Payroll Software

Affiliate Software

HOA Software

Reselling Platform

HCM Providers

Property Management

Healthcare Market Research Platforms

List

List

Request Body

Response Body

Sample 1

Response: 200