List

List

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

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).s. (e.g., Accepted, Rejected, Pending).

POST form1099w2/list 

Run in Postman

Request Body

Field	Type	Description
TaxYear	string	Tax year for which the 1099/W-2 returns should be listed.
FormTypes	Object[]	List of form types to filter the returns. Allowed values Allowed Values: "FORM1099NEC", "FORM1099MISC", "FORM1099K", "FORM1099INT", "FORMW2", "FORMW2G", "FORM5498SA"
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
PayerTINType	String	TIN type of the business. Allowed values Allowed Values: "EIN", "SSN", "QI-EIN", "ITIN", "WP-EIN", "WT-EIN", "NQI-EIN", "IRSN"
PayerLast4TIN	String	Last four digits of the business TIN.
Recipient	object	Recipient details used to identify the recipient.
RecipientId	GUID	Unique Recipient ID generated by TaxBandits.
PayeeRef	String	Optional Your unique reference for the recipient. Size Range: 50
RecipientNm	String	Name of the recipient. Size Range: 75
RecipientTINType	String	TIN type of the recipient. Allowed values Allowed Values: "EIN", "SSN", "QI-EIN", "ITIN", "WP-EIN", "WT-EIN", "NQI-EIN", "IRSN"
RecipientLast4TIN	String	Last four digits of the recipient'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: "CREATED", "TRANSMITTED", "SENT TO AGENCY", "ACCEPTED", "REJECTED", "ACCEPTEDWITHERRORS"
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: "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: "CREATED", "ORDER_CREATED", "EMAIL_SENT", "DOWNLOADED_FORM", "VIEWED_FORM"
PostalStatus	Object[]	One or more postal distribution statuses to filter the results. Allowed values 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
Form1099W2Records	Object[]	List of 1099/W-2 return records.
TaxYear	string	Tax year of the listed returns.
FormType	string	Form type of the listed 1099/W-2 returns.
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.
RecipientId	GUID	Unique ID of the recipient.
PayeeRef	string	Your unique reference for the recipient.
RecipientNm	string	Name of the recipient.
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 when 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 1099/W-2 returns using payer, submission, filing status, state status, and distribution filters.

Sample 1

{
"TaxYear": "2026",
"FormTypes": [
  "FORM1099NEC",
  "FORM1099MISC"
],
"Business": {
  "BusinessId": null,
  "PayerRef": "Payer132",
  "BusinessNm": "Steven LLC",
  "PayerTINType": "EIN",
  "PayerLast4TIN": null
},
"Recipient": {
  "RecipientId": null,
  "PayeeRef": "Payee123",
  "RecipientNm": null,
  "RecipientTINType": "SSN",
  "RecipientLast4TIN": 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

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

Response: 200

{
"Form1099W2Records": [
  {
    "TaxYear": "2026",
    "FormType": "Form1099NEC",
    "SubmissionId": "e50c27b8-631c-45f0-be19-f786fc69ba60",
    "RecordId": "cfd6fe66-ac9f-49f7-b8a3-2d064abeeb9b",
    "BusinessId": "bbd57dc2-d948-40cd-b67b-9fe06cc62218",
    "BusinessNm": " ",
    "PayerRef": "Snow123",
    "RecipientId": "4fb305b7-f0d7-4093-9152-93f07313b606",
    "PayeeRef": "DAI001",
    "RecipientNm": null,
    "FederalStatus": {
      "StatusCd": "FED-002",
      "Status": "TRANSMITTED",
      "Info": "Transmitted to IRS",
      "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
}