List

List

This endpoint retrieves a list of ACA form records created in TaxBandits. You can filter results using payer, recipient, submission, date range, and filing status details.

POST acaformsutility/list 

Run in Postman

Request Body

Field	Type	Description
TaxYear	string	Tax year for which ACA records should be listed.
FormType	string	ACA form type to filter results. Allowed values "FORM1095B", "FORM1095C"
Business	object	Business details used to identify the payer.
BusinessId	GUID	Unique Business ID generated by TaxBandits.
PayerRef	string	Optional Your unique reference for the payer. Can be used instead of BusinessId. Size Range: ..75
BusinessNm	string	Legal name of the business.
TINType	string	TIN type of the business. Allowed values "EIN", "SSN"
PayerTIN	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 "SSN", "ITIN"
RecipientLast4TIN	string	Last four digits of the recipient TIN.
SubmissionId	GUID	Unique ID assigned by TaxBandits to the submission.
Federal	object	Filters returns based on the federal filing status.
Status	string[]	One or more federal return statuses to filter the results. Allowed values "CREATED", "TRANSMITTED", "SENT_TO_AGENCY", "ACCEPTED", "REJECTED"
State	object	Filters returns based on the state filing status.
StateCd	String	Two-letter state abbreviation for which the return was transmitted.
Status	Object[]	One or more state return statuses to filter the results. 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 "CREATED", "ORDER_CREATED", "EMAIL_SENT","DOWNLOADED_FORM", "VIEWED_FORM"
OAStatusCd	string	Status code representing the online access status.
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
FormACARecords	Object[]	List of ACAForm return records.
TaxYear	string	Tax year of the listed returns.
FormType	string	Form type of the listed ACAForm returns.
SubmissionId	GUID	Unique identifier of a 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.
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.
CreatedTs	String	Date and time when the return was created.
TotalRecords	number	Total number of records.
TotalPages	number	Total number of pages.
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.

Payload

Request JSON

Sample	Description	Action
Sample 1	List ACA records using payer, recipient, and filing-status filters.

Sample 1

{
"TaxYear": "2026",
"FormTypes": [
  "FORM1095B"
],
"Business": {
  "BusinessId": null,
  "PayerRef": "Payer132",
  "BusinessNm": "Steven LLC",
  "PayerTINType":"EIN", 
  "PayerLast4TIN": null
},
"SubmissionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"Federal": {
  "Status": [
    "CREATED",
    "TRANSMITTED",
    "SCHEDULED"
  ]
},
"State": {
  "StateCd": [
    "SC",
    "MD"
  ],
  "Status": [
    "CREATED",
    "SCHEDULED "
  ],

},
"Distribution": {
  "OAStatus": [
    "OPENED",
    "VIEWED"
  ],
  "OAStatusCd": null,
  "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

{
"FormACARecords": [
  {
    "TaxYear": "2026",
    "FormType": "Form1095C",
    "SubmissionId": "e50c27b8-631c-45f0-be19-f786fc69ba60",
    "RecordId": "cfd6fe66-ac9f-49f7-b8a3-2d064abeeb9b",
    "BusinessId": "bbd57dc2-d948-40cd-b67b-9fe06cc62218",
    "BusinessNm": " ",
    "PayerRef": "Snow123",
    "AttachedCnt": 1,
    "EmployeeDetails": [
              {
                  "EmployeeId": "cc3e409b-c34f-492b-ac1a-2a5333e823b4",
                  "EmployeeName": "Steve Michal Waugh Sr",
                  "SSN": 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"
      },
    "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
}

cURL

curl --location '<APIURL>/v2.0.0/acaformutility/list' \
--header 'Content-Type: application/json' \
--header 'Authorization: <ACCESS_TOKEN>' \
--data '{
"TaxYear": "2026",
"FormType": "FORM1095B",
"Business": {
  "BusinessId": null,
  "PayerRef": "PAYER001",
  "BusinessNm": "Steven LLC",
  "TINType": "EIN",
  "PayerTIN": null
},
"Recipient": {
  "RecipientId": null,
  "PayeeRef": "EMP001",
  "RecipientNm": "John Smith",
  "RecipientTINType": "SSN",
  "RecipientLast4TIN": null
},
"SubmissionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"Federal": {
  "Status": [
    "CREATED",
    "TRANSMITTED"
  ]
},
"FromDate": null,
"ToDate": null,
"Page": 1,
"PageSize": 100
}'