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.
/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. |