Using a web service call to verify a small business energy exemption

If a utility vendor chooses not to retain copies of small business energy exemption certificates issued by DOR to customers, they may use a web service (REST) call to verify the exemption.

Updated: July 31, 2023

Overview

If a utility vendor chooses not to retain copies of small business energy exemption certificates issued by DOR to customers, they may use a web service (REST) call to verify the exemption.   With this option, a certificate number or FEIN can be sent programmatically to a secure site and a systemic response will be received.  To utilize this service, a vendor must first provide DOR with the IP address(es) from which the web call will be made, so the IP address can be white-listed by the Department. 

Testing and beginning the process

To test or begin using this process, logon to your MassTaxConnect account and send the IP address(s) associated with your business in a message with the subject “SBE exemption”  along with your contact information (name, company name, phone number, and e-mail).  You will be notified once your IP address has been white-listed with the Department. After you receive notification the instructions for accessing the verification method for the Web Service (REST) feature are as follows:

• Base URL
• Parameters
• Example of the full call
• Response

Base URL

https://sgw.dor.state.ma.us/dev/sbse (this URL is to be used for connectivity and data response testing.  Once a connection and valid response is successful, the Department will publish a URL that will be utilized for live data)

Parameters

• FEIN – 9 character string that only allows numeric (no dash
• Certificate ID – Numeric without the prefix characters “EE
• Both or either of the parameters can be used but at least one of them must be present.

Example of the full call

Once the HTTP Get has completed you will get the following fields in an XML format if a successful match has been found

Response

Once the HTTP Get has completed you will get the following fields in an XML format if a successful match has been found

• CertificateNumber  – Certificate number that was either given or matches the FEIN that was supplied
   
• FEIN – Federal Taxpayer Identification number that was either given or matches the Certificate Number supplied
   
• ExemptionStartDate – The start date of the businesses exemption
   
• ExemptionEndDate – The date in which the exemption is no longer valid
   
• ExemptionIsActive – true/False value based on whether the current date is in between the start and end date of the exemption.
   
• ServiceLocation – A repeating list for each service location which contains the following fields
   
  • Name – Name of the location picked by the exemption holder
     
  • Street – Street of the service location
     
  • Unit Type – unit type of the service location
     
  • Unit – unit of the service location
     
  • County – country of the service
     
  •  Zip – zip of the service location
     
  • Country – country of the service location
     

If no results are found, the Results node will come back empty.

Below is an example XML for the response as well as a schema detailing the response

•  Example XML for the response 
• Schema (will be provided after IP address is white-listed)