Create

Create

Use this endpoint to generate a new withholding form for the state of Virginia.

VA-5Q (Quarterly Form):

• Used for reporting state withholding taxes on a quarterly basis.

• Employers who withhold Virginia state income tax from employee wages and are not required to file monthly use this form.

• Covers the tax period of 3 months (quarterly).

VA-5M (Monthly Form):

• Used for reporting state withholding taxes on a monthly basis.

• Employers who withhold large amounts of Virginia state tax or meet the threshold requiring monthly reporting must use this form.

• Covers one month of withholding.

POST StateFilings/VA5QWH/Create 

Run in Postman

Request Body

Field	Type	Description
SubmissionId	Guid	Unique identifier created by TaxBandits for each submission. Not required when you are creating a return.
StateWHRecords	Object []	Object to create VA-5Qs
SequenceId	String	A unique number given by an inbound application to identify failed records. Size Range: ..10
ReturnHeader	Object	Identifies the supporting details of Form VA-5Q.
Qtr	String	The Quarter for which Form VA-5Q needs to be filed. Allowed values "Q1", "Q2", "Q3", "Q4"
TaxYr	String	The tax year for which Form VA-5Q needs to be filed. Allowed values 2025
BusinessId	String	Optional Use the unique BusinessId (Generated by TaxBandits) you received in the response of the Business CREATE Endpoint. If you do not have a BusinesId, ignore the field. By giving the BusinessId, you do not have to provide all the business information again.
Business	Object	The details of the business you’re filing for.
BusinessNm	String	Name of the business. Size Range: ..75
PayerRef	string	Optional An unique identifier for each payer completing their information. This identifier can be used in future references of the payer in the API. Size Range: ..50
TradeNm	String	Optional Name under which the business operates. Size Range: ..75
IsEIN	Boolean	When true, identifies the business with an EIN.
EINorSSN	String	When IsEIN is true, use Employer Identification Number (EIN). When IsEIN is false, use Social Security Number (SSN). Size Range: 9-11
Email	String	Email address of the business. Size Range: ..100
IsForeign	Boolean	When true, identifies the business as having a foreign address.
USAddress	Object	If IsForeign is false, pass the US address of the business.
Address1	String	Employer/Payer’s US address (street address or post office box). Size Range: ..46
Address2	String	Optional Employer/Payer’s suite or apartment. Size Range: ..46
City	String	Employer/Payer’s city. Size Range: ..50
State	String	Employer/Payer’s state. Size Range: 2 Allowed values "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", etc.
ZipCd	String	Employer/Payer’s zip code. Size Range: 5..10
ForeignAddress	Object	If IsForeign is true, pass the foreign address of the business.
Address1	String	Employer/Payer’s foreign address (street address or post office box). Size Range: ..50
Address2	String	Optional Employer/Payer’s suite or apartment. Size Range: ..50
City	String	Employer/Payer’s city. Size Range: ..50
ProvinceOrStateNm	String	Employer/Payer’s province or state name. Size Range: ..50
Country	String	Employer/Payer’s country. Size Range: 2 Allowed values "AF", "AX", "AL", "AG", "AQ", "AN", "AO", "AV", "AY", "AC", "AR", "AM", "AA", "AT", "AS", etc.
PostalCd	String	Employer/Payer’s postal code. Size Range: ..16
ReturnData	Object[]	Identifies the Form VA-5Q data.
FormVA5Q	Object	Virginia withholding quarterly tax return.
WHIdNum	String	Virginia withholding account number. Allowed Format: "30-999999999F-001" or "30999999999F001"
L1VAWHAmt	Number	Total Virginia income tax withheld for the quarter Size Range: 0-99999999.99
IsL1OverPayment	Boolean	If True identifies that Adjustment is made for the over payment reporting
IsL2UnderPayment	Boolean	If True identifies that Adjustment is made for the under payment reporting
L2AdjAmt	Number	Previous period(s) adjustments Size Range: 0-99999999.99
L3TotAdjAmt	Number	Total adjustment totals of the quarter Size Range: 0-99999999.99
L4PenaltyAmt	Number	Penalties for the quarter Size Range: 0-99999999.99
L5InterestAmt	Number	Total interest amount for the quarter Size Range: 0-99999999.99
L6TotAmtDue	Number	Total amount due for the quarter Size Range: 0-99999999.99
StatePayment	Object	Object to identify the state payment details
RoutingTransitNumber	String	Bank routing number for state payment Size Range: 9
BankAccountNumber	String	Bank account number for state payment Size Range: ..17
PaymentAmt	Number	Payment amount for state payment Size Range: 0-99999999.99

Response Body

Field	Type	Description
SubmissionId	Guid	Unique identifier of a submission
SuccessRecords	object[]	It will show the detailed information about the success status of Form VA-5Q Records
SequenceId	string	A unique number given by an inbound application to identify particular records.
BusinessId	Guid	Unique identifier of a Business
PayerRef	string	Unique identifier of the payer
RecordId	Guid	An unique identifier generated by TaxBandits when a VA-5Q return is created
FormType	string	Denotes the type of withholding form (Form VA-5Q).
Status	string	Returns the record status of return.
StatusTs	string	Date and time of the return created.
Info	string	Returns the information about the return
Errors	object[]	Shows error information of state returns of Form VA-5Q
Id	string	Returns the validation error Id.
Name	string	Name of the validation error.
Message	string	Description of the validation error.
ErrorRecords	object[]	It will show the detailed information about the error status of Form VA-5Q Records.
SequenceId	string	A unique number given by an inbound application to identify particular records. The Sequence ID will be returned in the Response for your reference.
RecordId	Guid	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.

Request JSON

{
   
    "SubmissionId": "0199e75c-0735-77da-a40d-90459b8b9495",
    "StateWHRecords": [
        {
            "Sequence": "001",
            "RecordId": "0199e75c-084f-730c-9db2-238dbdc5e014",
            "ReturnHeader": {
                "Qtr": "Q4",
                "TaxYr": "2025",
                "Business": {
                    "BusinessId": "351fc0b4-2568-40af-a403-4c08468cdd95",
                    "BusinessNm": "SnowDaze LLC",
                    "PayerRef": null,
                    "FirstNm": null,
                    "MiddleNm": null,
                    "LastNm": null,
                    "Suffix": null,
                    "TradeNm": "",
                    "IsEIN": true,
                    "EINorSSN": "34-2093733",
                    "Email": "john@sample.com",
                    "ContactNm": null,
                    "Phone": null,
                    "PhoneExtn": null,
                    "Fax": null,
                    "BusinessType": null,
                    "SigningAuthority": null,
                    "KindOfEmployer": null,
                    "KindOfPayer": null,
                    "IsBusinessTerminated": false,
                    "IsForeign": false,
                    "USAddress": {
                        "Address1": "12 main st",
                        "Address2": null,
                        "City": "Rock Hill",
                        "State": "SC",
                        "ZipCd": "29730"
                    },
                    "ForeignAddress": null,
                    "ACADetails": null
                }
            },
            "ReturnData": {
                "FormVA5Q": {
                    "WHIdNum": "30-999999999F-001",
                    "L1VAWHAmt": 300,
                    "L2AdjAmt": 200,
                    "IsL2OverPayment": true,
                    "IsL2UnderPayment": false,
                    "L3TotAdjAmt": 200,
                    "L4PenaltyAmt": 100,
                    "L5InterestAmt": 100,
                    "L6TotAmtDue": 400
                },
                "StatePayment": {
                    "BankRoutingNum": "217555555",
                    "BankAccountNum": "0000000001",
                    "PaymentAmt": 100
                }
            }
        }
    ]
}

Response JSON

200

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

{
  "StatusCode": "200",
  "StatusName": "Ok",
  "StatusMessage": "Successful API call",
  "SubmissionId": "0199e6f0-2c54-752a-a1a4-efe2be1e13a6",
  "SuccessRecords": [
      {
          "SequenceId": "001",
          "BusinessId": "136f3b7f-4734-42be-894c-dc7c68258ea7",
          "PayerRef": null,
          "RecordId": "0199e6f0-2d46-7068-bb26-ba57f29784f5",
          "FormType": "VA5Q",
          "Status": "CREATED",
          "StatusTs": "2025-10-15 04:15:23 -04:00",
          "Info": null,
          "Errors": null
      }
  ],
  "ErrorRecords": null,
  "Errors": null
}

300

Multi-status Response - You'll get the below response when multiple statuses are included.

{
  "StatusCode": "300",
  "StatusName": "MultiStatus",
  "StatusMessage": "Multiple statuses are available for the request",
  "SubmissionId": "0199e75c-0735-77da-a40d-90459b8b9495",
  "SuccessRecords": [
      {
          "SequenceId": "001",
          "BusinessId": "351fc0b4-2568-40af-a403-4c08468cdd95",
          "PayerRef": null,
          "RecordId": "0199e75c-084f-730c-9db2-238dbdc5e014",
          "FormType": "VA5Q",
          "Status": "CREATED",
          "StatusTs": "2025-10-15 06:13:12 -04:00",
          "Info": null,
          "Errors": null
      }
  ],
  "ErrorRecords": [
      {
          "SequenceId": "002",
          "RecordId": null,
          "Errors": [
              {
                  "Id": "S00-000412",
                  "Name": "StateWHRecords[1].ReturnData.FormVA5Q.L1VAWHAmt",
                  "Message": "VA Income Tax Withheld is Required"
              }
          ]
      }
  ],
  "Errors": [
      {
          "Id": "S00-000184",
          "Name": "Error Records",
          "Message": "Some of the records are errored. Please read the Error Records for more details."
      }
  ]
}

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",
  "SubmissionId": null,
  "SuccessRecords": null,
  "ErrorRecords": [
      {
          "SequenceId": "001",
          "RecordId": null,
          "Errors": [
              {
                  "Id": "S00-000406",
                  "Name": "StateWHRecords[0].ReturnData.FormVA5Q.WHIdNum",
                  "Message": "Withholding Account Number is required."
              }
          ]
      }
  ],
  "Errors": null
}

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"
      }
  ]
}