Individual Method POST

The TAXPAYER method returns a summary, by tax period, of all relevent data that creates a tax profile of the individual. Such things as Total Income, AGI, Form filed, file date, if a balance is owed, and any actions the IRS has taken or are planning on taking.


Request Path

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


/Individual Request application/json

This method uses the Tax Identification Number (SSN) for an individual to retrieve all relevant tax data points by period (YYYYMM).

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.
  • ssn* 9-digit tax id (no spaces or hypens) of the individual taxpayer

Example call request body for the individual method

{ "companyId":"enco45100", "ssn":"222222222" }

Response Body application/json

The following is a list of all possible fields. NULL fields are not returned.

Attributes

  • SSN The SSN sent in the request
  • Data An array of objects for each period available from the IRS
    • Period The tax year and month this list applies to in YYYYMM format
    • Form The IRS form where the data was retrieved
    • FormType Indicates the IRS form type (ACTR, RETR, RECA, CIVPEN, etc.)
    • UpdateDate The date the data was last retrieved from the IRS
    • FileingStatus The filing status of the taxpayer
    • AnnualForm The annual form the taxpayer files
    • AIG The Adjusted Gross Income of the taxpayer
    • TotalIncome The total income filed
    • IRSBalance The balance owed by the taxpayer to the IRS
    • FileDate The date the IRS received the tax form from the taxpayer
    • LienDate If populated, the date a lien was issued to the taxpayer
    • LateDate If populated, the date after the deadline a tax form was received
    • LevyDate If populated, the date a levy was issued to the taxpayer
    • AuditDate If populated, the date an audite is planned for the taxpayer
    • IADate If populated, the date a payment plan was issued to the taxpayer
    • CNCDate If populated, the date a taxpayer was given Curently Not Collectable (CNC) status
    • OfferDate If populated, the date an offer from the IRS was issued to the taxpayer
    • AgencyDate If populated, the date
    • SFRDate If populated, the date a Substitue of return was filed by the IRS
    • PassportDate If populated, the date the taxpayers passport was revoked
    • PaymentDate If populated, the date when the taxpayer last made a payment
    • ExtensionDate If populated, the date the taxpayer was given an extension on the filing deadline

Example response body for the individual method

{ "SSN": "XXX-XX-2222", "Data": [ { "Period": 200012, "Form": "1040", "FormType": "ACTR", "UpdateDate": "06/13/2021", "FilingStatus": "SINGLE", "AnnualForm": "1040", "AGI": 2599.00, "TotalIncome": 74123.00, "IRSBalance": 0.00, "FileDate": "05/07/2001" }] }

Example response when taxpayer is not in the system.

{"taxpayer":"Waiting on IRS"}

The possible reponse codes are below.

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.