Skip to main content
Both lookup endpoints, Look up client account by EIN and Look up taxpayer by EIN, return a currentStatus object and identify taxpayers the same way. The lookups are part of delegate access. This page explains how to read a result.

​
currentStatus

Always present on a response. An object with a status and two badge URLs, one per theme:
badgeGraphicUrl and badgeGraphicUrlDark are publicly hosted SVGs you can embed directly to display the status. Use badgeGraphicUrl on light backgrounds and badgeGraphicUrlDark on dark ones.

​
Status values

CompliantCompliantCompliant: No balance owed and no missing required returns.
Active resolutionActive resolutionActiveResolution: A balance is owed, and active installment agreements cover all of it. No missing required returns.
At riskAt riskAtRisk: A balance is owed that active installment agreements do not fully cover. No missing required returns and no active collection threat.
Not compliantNot compliantNotCompliant: Missing required returns or an active collection threat.
Data pendingData pendingDataPending: TaxRock does not have this taxpayer’s data yet. Its financial totals are null and its lists are empty. Account-level totals read 0.
Not monitoredNot monitoredNotMonitored: TaxRock is not monitoring a business with that EIN for the user you have authenticated the request on behalf of. Appears at the top level only, where result is null.

​
Account-wide status (client-account lookup only)

On the client-account lookup, the top-level currentStatus is client-account-wide: the least favorable status across the account’s taxpayers. An account with no issues found and incomplete data reads DataPending.

​
Balances by year

Every taxpayer and the client account carry balanceByYear, the balance broken down per tax year, most recent year first. Each entry splits the year into principal, interest, penalties, allCredits, and unallocatedCredits, with amountDue as the net owed for the year. The top-level amountDue is the total across all years, and balanceByYear is the breakdown behind it. The account’s balanceByYear aggregates its taxpayers.

​
Liens

Every taxpayer carries liens, the full list of federal tax liens on that taxpayer in any state (Active, Released, or Removed), alongside a lienSummary of rollups. Each lien has its filingDate, status, the currentSecuredBalance it secures, and the securedPeriods (form and tax period) still secured. A removed lien also carries fullyRemovedDate and balanceAtRemoval. lienSummary (also on the client account, aggregated across its taxpayers) gives:
  • hasActiveLienSecuringNonZeroBalance: true when an active lien secures a balance above zero.
  • totalBalanceSecuredByLiens: total secured across active liens.
  • mostRecentActiveLienFilingDate: filing date of the most recently filed active lien, or null when there are none.

​
Installment agreements

Every taxpayer carries installmentAgreements, the full list in any state (Requested, Pending, Active, PaidOff, Defaulted, or Removed), alongside an installmentAgreementSummary of rollups. Each agreement has its status, startDate and endDate, currentBalance, totalPaid, and the coveredPeriods it currently covers. A closed agreement also carries balanceAtClose. Requested: the agreement has been requested and the IRS has not acted on it. Its startDate is the request date, and its coveredPeriods are the periods requested. installmentAgreementSummary (also on the client account, aggregated across its taxpayers) gives:
  • hasBalanceNotCoveredByActiveIA: true when a balance is owed that no active agreement covers.
  • balanceNotCoveredByActiveIA: the total of that uncovered balance.
  • periodsNotCoveredByActiveIA: the specific form-periods with a balance not covered by an active agreement.

​
Identifying the matched taxpayer

  • isLookupMatch (client-account lookup only): true on the row (in taxpayers[] or pendingTaxpayers[]) whose TIN matched the EIN you looked up.
  • tin: unformatted digits. For businesses it is the raw nine-digit EIN. For individuals it is censored to the last four digits (xxxxx0123).
  • isTinCensored: true when tin is censored.

​
Pending taxpayers

pendingTaxpayers[] (client-account lookup only) are taxpayers added to the account but not yet onboarded. Each has id, name, type, isLookupMatch, tin (null if not provided yet), and isTinCensored, with no status or financial fields.

​
Errors

A missing or malformed businessEin returns 400 with an { error, message } body:
  • invalid_request: businessEin was absent, empty, or not a string.
  • invalid_ein: businessEin did not contain nine digits (dashes and spaces are ignored).
The OAuth token endpoint uses the OAuth-standard { error, error_description } shape instead of this { error, message } shape.