Alerts Method POST

The ALERTS method allows a company to check monitoring for all taxpayers with which the company has obtained consent from the IRS Through TaxStatus. The JSON returned will be all alerts from the IRS since the last day, minus 24 hours, the ALERTS call was made or the last 2 weeks if first time it is called. The IRS updates these statuses nightly. So generally you would only need to call once per day.

The alert types TaxStatus is monitoring are as follows:

  • Amended - An amended tax return has been filed by the taxpayer or the IRS in case of a decrepency found.
  • Audit - information pertaining to an IRS audit.
  • Bankruptcy - information pertaining to a bankruptcy.
  • Credits - information pertaining credits given and taken away by the IRS on an account.
  • ERC- information pertaining to Covid relief.
  • Extension- information pertaining to extension being filed.
  • Filing - information pertaining to whether a taxpayer has filed their annual or quarterly taxes.
  • Levy - information pertaining to levies issued/revoked by the IRS.
  • Lien - information pertaining to liens issued/revoked by the IRS.
  • Notice - notiices sent out by the IRS to the taxpayer.
  • Passport- information pertaining to whether a passport will be revoked or reinstated.
  • Payment - information pertaining to payments being made by taxpayer or being denied by the IRS.
  • Penalty - information pertaining to penalties being placed
  • Refund - refund issued to taxpayer.
  • Resolution information pertaining to a resolution the taxpayer has established or has fallen out.

Request Path

Submit all alerts requests to the following path.

Path

You will obtain the API endpoint after you register on your account page.

Headers

Each request must an OAuth2 tokan and your company Id, assigned by TaxStatus, in the header.

Authorization
euid

Query String Parameters

Query string parameters are not supported on this method.

/Alerts Request application/json

Post the following payload to get alerts from the IRS for the taxpayers your company has set up.

Attributes

  • companyId* The company Id of the company this call is on behalf of. If the call is not on behalf of another company, then the registered company Id TaxStatus assigned during the registration process used in the euid field in the header.

Example call request body for the alerts method.

{ "companyId": "enco45100" }

Response Body application/json

Attributes

  • TIN The Tax Identification Number sent in the request
  • Name The last name or business name of the taxpayer
  • Data An array of objects for each period available from the IRS
    • Topic The category the alert falls into such as LIEN or PAYMENT.
    • ReportPeriod The report period the alert applies. Each period is a separate account with the IRS. Some alerts can apply to multiple periods.
    • ItemDescription The description of the alert.
    • ItemAmount The dollar amount that pertains to the alert.
    • ItemDate The date the alert will be enforced. This can be in the future.

Example response body for the alerts method

[{ "TIN": "XXXXX2222", "Name": "SMITH", "Data": [{ "Topic": "REFUND", "ReportPeriod": 202112, "ItemDescription": "Refund issued", "ItemAmount":"$120.00", "ItemDate": "12-15-2021" }] }, { "TIN": "XXXXX3333", "Name": "JONES", "Data": [{ "Topic": "NOTICE", "ReportPeriod": 202012, "ItemDescription": "Notice issued NOTICE1444", "ItemAmount":"$0.00", "ItemDate": "12-02-2021" }, { "Topic": "PAYMENT", "ReportPeriod": 201612, "ItemDescription": "Dishonered advanced payment of tax owed", "ItemAmount":"$0.00", "ItemDate": "12-17-2021" }] }, { "TIN": "XXXXX4444", "Name": "HENDRICKS", "Data": [{ "Topic": "LIEN", "ReportPeriod": 201912, "ItemDescription": "Lien placed on assets due to balance owed", "ItemAmount":"$0.00", "ItemDate": "12-17-2021" }, { "Topic": "LIEN", "ReportPeriod": 201612, "ItemDescription": "Lien placed on assets due to balance owed", "ItemAmount":"$0.00", "ItemDate": "12-17-2021" }, { "Topic": "PAYMENT", "ReportPeriod": 201612, "ItemDescription": "payment", "ItemAmount":"$2380.50", "ItemDate": "12-17-2021" }, { "Topic": "LIEN", "ReportPeriod": 201712, "ItemDescription": "Lien placed on assets due to balance owed", "ItemAmount":"$0.00", "ItemDate": "12-17-2021" }, { "Topic": "Address Change", "ReportPeriod": 201612, "ItemDescription": "123 M", "ItemAmount":"", "ItemDate": "12-17-2021" }] }]

The reponse codes for the alerts call are standard HTML response codes.

Response Codes

HTTP Status Code Description Explanation
200 Accepted/OK The request has been accepted with no issues
400 Bad Request You are missing some required fields or the Json in the body is missing or malformed
403 Forbidden You do not have authorization to make this call. Possibly your comapany Id is invalid or you are calling on behalf of a company with which you dont have authority.