List

List

Use this endpoint to retrieve a list of all the withholding forms that have been created or transmitted to the state agencies for a specific business.

Key Points

• The list can be filtered by TIN, SubmissionId, Filing Status and Quarter
• You can also filter the results by a Date Range to narrow down results.

GET StateFilings/List   

Run in Postman

Request Params

Field	Type	Description
TaxYear	string	Tax year to be filed.
BusinessId	Guid	Unique Identifier of a business
SubmissionId	Guid	Unique identifier of a submission
TIN	string	List the withholding or UI records based on the given TIN (EIN).
Status	string	List the withholding or UI records based on the status
Quarter	string	List the withholding or UI records based on the quarter
FromDate	string	Enter a date from which the records need to be listed in MM/DD/YYYY format.
ToDate	string	Enter a date till which the withholding or UI records created are to be listed in MM/DD/YYYY format.

Response Body

Field	Type	Description
SubmissionId	Guid	Unique identifier of a submission
BusinessId	Guid	Unique identifier of a Business.
PayerRef	string	Unique identifier of the payer.
StateFilingRecords	Object	Pulls withholding or UI records with Success and Error statuses
SuccessRecords	object[]	It will show the detailed information about the success status of withholding or UI returns
RecordId	Guid	Unique identifier of a record
State	string	Returns the State code of the withholding or UI return
FormType	string	Returns the Form type
Status	string	Returns the record status.
PDFUrl	string	Link to download the PDF
ErrorRecords	object []	Contains the error records
RecordId	Guid	Unique identifier of a record
State	string	Returns the State code of the withholding or UI return
FormType	string	Returns the Form type
Status	string	Returns the record status.
Errors	object[]	Shows error information
Id	string	Returns the validation error Id.
Name	string	Name of the validation error.
Message	string	Description of the validation error.
TotalRecords	number	Total number of records listed in the response.
TotalPages	number	Total number of pages
Page	number	Returns the page number in which the records are listed
PageSize	number	Number of records listed in each page.
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

"StateFilings/List?TaxYear=2025&State=SC&BusinessId=08631c17-564c-433d-a3ea-ff7f6f3ff1e6&SubmissionId=08631c17-564c-433d-a3ea-ff7f6f3ff1e6&TINType=EIN&TIN=123456789&Status=ACCEPTED&Quarter=Q1&FromDate=01/01/2025&ToDate=12/31/2025&Page=1&PageSize=25"

Response JSON

200

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

{
  "StatusCode": "200",
  "StatusName": "Ok",
  "StatusMessage": "Successful API call",
  "StateFilingRecords": [
      {
          "BusinessId": "846d6e66-80fc-4f0c-a712-8ccf8b18ed70",
          "SubmissionId": "0199386b-0468-700b-a1ac-7b6960720c1c",
          "RecordId": "0199386b-052d-700c-9720-723b15bacea8",
          "PayerRef": null,
          "BusinessNm": "HH LLC",
          "State": "SC",
          "FormType": "SC1605",
          "TaxYr": "2025",
          "Qtr": "Q1",
          "Status": "ACCEPTED"
      },
      {
          "BusinessId": "5479d64b-12e6-44f6-9f3b-575226a6022a",
          "SubmissionId": "0199386b-0468-700b-a1ac-7b6960720c1c",
          "RecordId": "0199386b-105e-741b-af10-f2bd2a01c22e",
          "PayerRef": null,
          "BusinessNm": "HK LLC",
          "State": "SC",
          "FormType": "SC1606",
          "TaxYr": "2025",
          "Qtr": "Q4",
          "Status": "ACCEPTED"
      }
  ],
  "TotalRecords": 4,
  "TotalPages": 1,
  "PageSize": 100,
  "Errors": null
}

400

Bad Request Response - You'll get the below response when your API requests contain any validation errors.

{
  "StatusCode": "400",
  "StatusName": "BadRequest",
  "StatusMessage": "Validation error has occurred",
  "StateFilingRecords": null,
  "Errors": [
      {
          "Id": "S00-000192",
          "Name": "Business Id",
          "Message": "Invalid BusinessId. The given BusinessId does not match with any of the BusinessIds created in your account."
      }
  ]
}

401

Unauthorized Response - You'll get the below response when your API requests don't contain valid authentication credentials.

{
  "StatusCode": 401,
  "StatusName": "Unauthorized",
  "StatusMessage": "Invalid authorization credentials",
  "Errors": [
      {
          "Id": "AUTH-100018",
          "Name": "Authorization",
          "Message": "JWT EXPIRED"
      }
  ]
}