Skip to main content
Version: 1.7.3

Overview

Massachusetts employers who withhold state income tax from employee wages must register through MassTaxConnect and file Form M-941, the Employer's Return of Income Taxes Withheld, with the Massachusetts Department of Revenue (DOR).

The TaxBandits API supports the automation of Form M-941, Massachusetts's withholding return.

Forms supported​

FormTypeFiling frequencyDue date
Form M-941WHAssigned by DOR: monthly, quarterly, or annually, based on projected withholdingVaries by assigned frequency; quarterly filers: last day of the month following the quarter end

Key compliance notes​

  • Filing frequency assigned by the state. DOR assigns each employer a monthly, quarterly, or annual filing frequency based on projected annual withholding.

  • Zero filing required. Returns showing $0 tax due must still be e-filed through MassTaxConnect.

Before filing, you can simulate the entire verification flow in our Sandbox environment without submitting real data to state agencies. See how

Available endpoints​

Each endpoint below is specific to Massachusetts's withholding Form M-941.

To use the following endpoints, you must first call the Auth method to obtain an access token. Include this token in your request header as a Bearer token. Refer to OAuth 2.0 Authentication for details on JWT-based authentication.

  • Create — Generates a new Form M-941 withholding return for the specified tax year and reporting period.

  • Update — Modifies the details of a previously created Form M-941 return before it's transmitted.

  • Get — Retrieves the details of a previously created Form M-941 return.

Common endpoints (utility)​

These endpoints share the same payload structure across all states, and apply uniformly whether you're working with a withholding form or a UI form:

  • List: Retrieves a list of forms created for a specific business or period.
  • Delete: Removes an in-progress form before it's transmitted to the state.
  • Transmit: Submits a completed form to the corresponding state agency.
  • RequestPdfUrls: Returns a link to download the PDF version of a form (final).
  • Status: Checks whether a submitted form was accepted or rejected by the state.

As an alternative to polling the Status endpoint, you can configure a webhook for the event type Status Payroll Filings Status Change to receive automated status updates.