Skip to main content
Both lookup endpoints return a currentStatus object and identify taxpayers the same way. 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

These are the live badgeGraphicUrl graphics. Embed them directly to display the status.
CompliantCompliant: No outstanding balances the IRS could try and collect on and no unfiled, required returns within the last seven years.
Active resolutionActiveResolution: An outstanding balance is owed, but every balance-carrying period is covered by an active installment agreement. The debt is being worked down on IRS terms, and all required returns over the last seven years have been filed.
At riskAtRisk: An outstanding balance is owed that is not fully covered by an active installment agreement, but no severe issues or current collection threats. Worth attention.
Not compliantNotCompliant: A serious issue is present, such as unfiled required returns or an active collection threat.
Data pendingDataPending: TaxRock is still gathering the data. Onboarding or IRS authorization is in progress. A taxpayer with this status has null financial totals and empty balanceByYear, liens, and installmentAgreements, and account-level totals read 0.
Not 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. It is the worst status across the account’s taxpayers, except that a clean-so-far account with incomplete data reads DataPending rather than Compliant.

​
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 (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. 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, so you never have to infer the censoring policy from type.

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