Update
Update
Use this endpoint to update the information on existing M-941 forms that are already created for a specific employer (payer).
You cannot update a return once it has been transmitted.
PUTStateFilings/MAWH/UpdateRequest 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 Form M-941 |
| SequenceId | String | A unique number given by an inbound application to identify failed records. Size Range: 1-10 |
| ReturnHeader | Object | Identifies the supporting details of Form M-941 |
| Qtr | String | The quarter for which Form M-941 needs to be filed.Allowed values"Q1", "Q2", "Q3", "Q4" |
| TaxYr | String | The tax year for which Form M-941 needs to be filed.Allowed values"2025","2026" |
| Business | Object | The details of the business you're filing for. |
| BusinessNm | String | Name of the business. Size Range: 1-75 |
| PayerRef | string | Optional A unique identifier for each payer completing their information. This identifier can be used in future references of the payer in the API. Size Range: 1-50 |
| TradeNm | String | Optional Name under which the business operates. Size Range: 1-75 |
| IsEIN | Boolean | When true, identifies the business with an EIN. |
| EINorSSN | String | When IsEIN is true, use Employer Identification Number (EIN). Size Range: 9-11 |
| String | Email address of the business. Size Range: 1-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: 1-46 |
| Address2 | String | Optional Employer/Payer's suite or apartment. Size Range: 1-46 |
| City | String | Employer/Payer's city. Size Range: 1-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", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY", "AS", "FM", "GU", "MH", "MP", "PW", "PR", "VI", "AA", "AE", "AP" |
| 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: 1-50 |
| Address2 | String | Optional Employer/Payer's suite or apartment. Size Range: 1-50 |
| City | String | Employer/Payer's city. Size Range: 1-50 |
| ProvinceOrStateNm | String | Employer/Payer's province or state name. Size Range: 1-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", "AU", "AJ", "BF", "BA", "FQ", "BG", "BB", "BO", "BE", "BH", "BN", "BD", "BT", "BL", "BK", "BC", "BV", "BR", "IO", "VI", "BX", "BU", "UV", "BM", "BY", "CB", "CM", "CA", "CV", "CJ", "CT", "CD", "CI", "CH", "KT", "IP", "CK", "CO", "CN", "CF", "CG", "CW", "CR", "CS", "IV", "HR", "CU", "UC", "CY", "EZ", "DA", "DX", "DJ", "DO", "DR", "TT", "EC", "EG", "ES", "EK", "ER", "EN", "ET", "FK", "FO", "FM", "FJ", "FI", "FR", "FP", "FS", "GB", "GA", "GG", "GM", "GH", "GI", "GR", "GL", "GJ", "GQ", "GT", "GK", "GV", "PU", "GY", "HA", "HM", "VT", "HO", "HK", "HQ", "HU", "IC", "IN", "ID", "IR", "IZ", "EI", "IS", "IT", "JM", "JN", "JA", "DQ", "JE", "JQ", "JO", "KZ", "KE", "KQ", "KR", "KN", "KS", "KV", "KU", "KG", "LA", "LG", "LE", "LT", "LI", "LY", "LS", "LH", "LU", "MC", "MK", "MA", "MI", "MY", "MV", "ML", "MT", "IM", "RM", "MR", "MP", "MX", "MQ", "MD", "MN", "MG", "MJ", "MH", "MO", "MZ", "WA", "NR", "BQ", "NP", "NL", "NC", "NZ", "NU", "NG", "NI", "NE", "NF", "CQ", "NO", "MU", "OC", "PK", "PS", "LQ", "PM", "PP", "PF", "PA", "PE", "RP", "PC", "PL", "PO", "RQ", "QA", "RO", "RS", "RW", "TB", "RN", "WS", "SM", "TP", "SA", "SG", "RI", "SE", "SL", "SN", "NN", "LO", "SI", "BP", "SO", "SF", "SX", "OD", "SP", "PG", "CE", "SH", "SC", "ST", "SB", "VC", "SU", "NS", "SV", "WZ", "SW", "SZ", "SY", "TW", "TI", "TZ", "TH", "TO", "TL", "TN", "TD", "TS", "TU", "TX", "TK", "TV", "UG", "UP", "AE", "UK", "UY", "UZ", "NH", "VE", "VM", "VQ", "WQ", "WF", "WI", "YM", "ZA", "ZI" |
| PostalCd | String | Employer/Payer's postal code. Size Range: 1-16 |
| ReturnData | Object | Identifies the Form M-941 |
| FormM941 | Object | Massachusetts withholding tax returns. |
| WHIdNum | String | Massachusetts withholding file number. Size Range: 1-9 |
| FilingFrequency | string | Filing frequency of the Form M-941 |
| Month | string | Select the month for the monthly filing period. Note: Required if the filing frequency is Monthly. |
| IsFinalReturn | Boolean | When true, indicates that it is a final return |
| NumOfEmployees | Number | Number of employees. Size Range: 0-9999999 |
| WHAmt | Number | Massachusetts income tax withheld from all sources for the filing period. Size Range: 0-99999999.99 |
| IsTaxPaid | Boolean | When true, identifies that the employer has made previous payments. |
| TaxPaidDetails | Object[] | Identifies the tax paid details. |
| Date | string | Enter the date the tax was paid. Format: MM/DD/YYYY or MM-DD-YYYY |
| Amount | string | Tax paid on the date mentioned. Size Range: 0-99999999.99 |
| TaxPaid | Number | Total tax paid for the filing period. Size Range: 0-99999999.99 |
| PrevCrdtAmt | Number | Previous credits payments made for the filing period. Size Range: 0-99999999.99 |
| TotTaxPaid | Number | Total payments and credits. Size Range: 0-99999999.99 |
| TotTaxDue | Number | Total tax due. Size Range: 0-99999999.99 |
| Penalty | Number | Total penalty amount, if applicable. Size Range: 0-99999999.99 |
| Interest | Number | Total interest due amount, if applicable. Size Range: 0-99999999.99 |
| TotBalanceDue | Number | Total due amount. Size Range: 0-99999999.99 |
| OverPaymentRecoveryType | string | Gets the overpayment recovery type. Whether to have the state refund the excess amount or apply it to next return.Allowed values"REFUND", "APPLYTORETURN" |
| StatePayment | Object | Object that contains information about the payment details |
| AccountType | string | Bank account type.Allowed values"PERSONAL_CHECKING", "PERSONAL_SAVINGS", "BUSINESS_SAVINGS", "BUSINESS_CHECKING" |
| BankNm | string | Bank account name of payment. Size Range: 1-30 |
| BankRoutingNum | string | Bank Routing Number of payment. Size Range: 9 |
| BankAccountNum | string | Bank Account Number for payment. Size Range: 1-17 |
| PaymentAmt | Number | Amount to be paid. Size Range: 0-9999999999.99 |
| PaymentReqDate | String | Date when the payment has to be made. Enter the date in the format: MM/DD/YYYY or MM-DD-YYYY (Example: 01/25/2026). |
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 M-941 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 | A unique identifier generated by TaxBandits when a M-941 return is created |
| FormType | string | Denotes the type of withholding form M-941. |
| 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 M-941 |
| 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 WH-1001 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 |
Request JSON
{
"SubmissionId": "019db3da-3f18-7303-bfe1-8b6c1c7134a3",
"StateWHRecords": [
{
"SequenceId": "001",
"RecordId": "019dcdb8-1dd8-7087-9baa-cd677b556eed",
"ReturnHeader": {
"Qtr": "Q1",
"TaxYr": "2025",
"Business": {
"BusinessId": "01f83dd9-6f9d-4ed4-a7ee-ec67a6f8d222",
"BusinessNm": "Snowdaze LLC",
"PayerRef": null,
"FirstNm": null,
"MiddleNm": null,
"LastNm": null,
"Suffix": null,
"TradeNm": "Mayfill Tech",
"IsEIN": true,
"EINorSSN": "74-5985016",
"Email": "james@sample.com",
"ContactNm": "John",
"Phone": "(789) 456-1231",
"PhoneExtn": null,
"Fax": null,
"BusinessType": "ESTE",
"SigningAuthority": {
"Name": "John",
"Phone": "(789) 789-7987",
"BusinessMemberType": "ADMINISTRATOR"
},
"KindOfEmployer": null,
"KindOfPayer": null,
"IsBusinessTerminated": false,
"IsForeign": false,
"USAddress": {
"Address1": "12 Main St",
"Address2": "Apt 2B",
"City": "Boston",
"State": "MA",
"ZipCd": "02108"
},
"ForeignAddress": null,
"ACADetails": null
}
},
"ReturnData": {
"FormM941": {
"WHIdNum": "WTH-74598501-001",
"FilingFrequency": "MONTHLY",
"Month": "NOV",
"IsFinalReturn": false,
"NumOfEmployees": "20",
"WHAmt": 200,
"IsTaxPaid": true,
"TaxPaidDetails": [
{
"Date": "11/21/2025",
"Amount": 60
},
{
"Date": "11/05/2025",
"Amount": 60
}
],
"TaxPaid": 120,
"PrevCrdtAmt": 60,
"TotTaxPaid": 180,
"TotTaxDue": 20,
"Penalty": 0,
"Interest": 0,
"TotBalanceDue": 20,
"OverPaymentRecoveryType": null
},
"StatePayment": {
"AccountType": "PERSONAL_CHECKING",
"BankNm": "IFB",
"BankRoutingNum": "021000021",
"BankAccountNum": "00133",
"PaymentAmt": 100,
"PaymentReqDate": "11/25/2025"
}
}
}
]
}
Response JSON
- 200
Success Response - This is a sample response for successful API requests.
{
"StatusCode": "200",
"StatusName": "Ok",
"StatusMessage": "Successful API call",
"SubmissionId": "019d1a68-e397-754b-ab1c-4c2edc8876ec",
"SuccessRecords": [
{
"SequenceId": "001",
"BusinessId": "2fa5381e-8c36-4fbd-8d66-8b0db29d3d90",
"PayerRef": "bdfjjghghdhgfh",
"RecordId": "019d1a68-fa42-753f-8b18-5d3b60fa6d1f",
"FormType": "WTH10001",
"Status": "CREATED",
"StatusTs": "2026-03-23 16:51:30 +05:30",
"Info": null,
"Errors": null
}
],
"ErrorRecords": null,
"Errors": null
}