Verify Method POST

The VERIFY method ensures that a taxpayer’s name and taxpayer ID have a valid match within the IRS system. This saves time retrieving tax documnets as it helps to eliminate errors and fraud. This method supports both individuals and businesses.

Note: The VERIFY method calls the IRS in real-tine and therefore the amount of seconds this call takes can vary. While most times the call is 1-4 seconds, sometimes the IRS system can slow down and this call can take up to 20 seconds or so. The IRS does not offer an SLA so you may need to take your method call timeout into considieration and extend it for this call.

Request Path

Submit all verify 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.

/Verify Request application/json

Post your customer's Tax Identification Number (TIN) for an individual (SSN) or business (EIN) along wiht the last name or business name to verify the IRS has a mutch in their system.

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.
  • tin* 9-digit tax id (no spaces or hypens) of the individual or company
  • isCompany* Zero (0) if tin is an SSN or one (1) if tin is an EIN
  • lastNameOrBusiness* Last name of individual or business name if business

Example call request body for an individual

{ "companyId": "enco45100", "tin": "222222222", "isCompany": 0, "lastNameOrBusiness": "SMITH" }

Example call request body for a business

{ "companyId": "enco45100", "tin": "555555555", "isCompany": 1, "lastNameOrBusiness": "ACME Inc" }

Response Body application/json

The reponse for the Verify request.

Attributes

  • TIN The Tax Identification Number sent in the request
  • Result Possible values are valid, invalid, queued, IRS system offline (if IRS system is not available). If response is queued, although this is rare, this may because the IRS system is backed up. You can have your API imediately make the call again with this taxpayer as usually the lag with the IRS is only a second or two.

    The IRS system does go down from time to time. So if you receive the status of IRS system offline, you will need to call back later. Typically it is down for very short periods at a time (10-20 min). However, we have experienced it down for 24-48 hours.

Example response bodys for the verify method

{ "TIN": "222222222", "Result": "valid" }

{ "TIN": "123456789", "Result": "IRS system down" }

{ "TIN": "333553333", "Result": "invalid" }

The reponse codes for the Verify 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.