Version: 1.7.3

Create

Use this endpoint to create the Massachusetts Form M-941 (Employer’s Quarterly Return of Income Tax Withheld) for an employer (payer) to report the total Massachusetts income tax withheld from employee wages for a specified calendar quarter and remit the corresponding withholding tax due to the Massachusetts Department of Revenue.

Note:

Form M-941 must be filed every quarter, even if no tax is withheld or no wages are paid.

POST StateFilings/MAWH/Create

Run in Postman

Request Body

Field	Type	Description
StateWHRecords	Object[]	Object to create Form M-941
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 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: ..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: ..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). 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", "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: ..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", "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: ..16
ReturnData	Object	Identifies the Form M-941
FormM941	Object	Massachusetts withholding tax returns.
WHIdNum	String	Massachusetts withholding file number. Size Range: ..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

{
    "StateWHRecords": [
        {
            "SequenceId": "001",
            "ReturnHeader": {
                "Qtr": "Q1",
                "TaxYr": "2025",
                "Business": {
                    "BusinessNm": "Snowdaze LLC",
                    "TradeNm": "Mayfill Tech",
                    "IsEIN": true,
                    "EINorSSN": "74-5985016",
                    "Email": "james@sample.com",
                    "ContactNm": "John",
                    "Phone": "7894561231",
                    "IsForeign": false,
                    "BusinessType": "ESTE",
                    "SigningAuthority": {
                        "Name": "John",
                        "Phone": "(789) 789-7987",
                        "BusinessMemberType": "ADMINISTRATOR"
                    },
                    "USAddress": {
                        "Address1": "12 Main St",
                        "Address2": "Apt 2B",
                        "City": "Boston",
                        "State": "MA",
                        "ZipCd": "02108"
                    },
                    "ForeignAddress": {
                        "Address1": null,
                        "Address2": null,
                        "City": null,
                        "ProvinceOrStateNm": null,
                        "Country": null,
                        "PostalCd": null
                    }
                }
            },
            "ReturnData": {
                "FormM941": {
                    "WHIdNum": "WTH-74598501-001",
                    "FilingFrequency": "MONTHLY",
                    "Month": "NOV",
                    "IsFinalReturn": false,
                    "NumOfEmployees": "20",
                    "WHAmt": "200.00",
                    "IsTaxPaid": true,
                    "TaxPaidDetails": [
                        {
                            "Date": "11/21/2025",
                            "Amount": "60.00"
                        },
                        {
                            "Date": "11/05/2025",
                            "Amount": "60.00"
                        }
                    ],
                    "TaxPaid": "120.00",
                    "PrevCrdtAmt": "60.00",
                    "TotTaxPaid": "180.00",
                    "TotTaxDue": "20.00",
                    "Penalty": "0.00",
                    "Interest": "0.00",
                    "TotBalanceDue": "20.00",
                    "OverPaymentRecoveryType": "REFUND"
                },
                "StatePayment": {
                    "AccountType": "PERSONAL_CHECKING",
                    "BankNm": "IFB",
                    "BankRoutingNum": "021000021",
                    "BankAccountNum": "00133",
                    "PaymentAmt": 100,
                    "PaymentReqDate": "11/25/2025"
                }
            }
        }
    ]
}

Response JSON

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

{
  "StatusCode": "200",
  "StatusName": "Ok",
  "StatusMessage": "Successful API call",
  "SubmissionId": "019db3da-3f18-7303-bfe1-8b6c1c7134a3",
  "SuccessRecords": [
      {
          "SequenceId": "001",
          "BusinessId": "bd759033-ca84-4c63-8320-7eb3b1a5201d",
          "PayerRef": null,
          "RecordId": "019db3da-8e13-778d-8842-e6d836564bab",
          "FormType": "M941",
          "Status": "CREATED",
          "StatusTs": "2026-04-22 11:52:18 +05:30",
          "Info": null,
          "Errors": null
      }
  ],
  "ErrorRecords": null,
  "Errors": null
}

W-9/W-8 Automation

1099 Automation

TIN Matching

W-2 Automation

941/940 Automation

1098-T Automation

ACA Automation

Extension Automation

1042-S Automation

Supported Forms

Gig Software

Payroll Software

Affiliate Software

HOA Software

Reselling Platform

HCM Providers

Property Management

Healthcare Market Research Platforms

Create

Create

Request Body

Response Body

Request JSON​

Response JSON​

Request JSON

Response JSON