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 a badgeGraphicUrl: 
{
  "status": "AtRisk",
  "badgeGraphicUrl": "https://taxrock-assets.s3.us-east-2.amazonaws.com/public/status-badges/taxrock-badge-at-risk.svg"
}
badgeGraphicUrl is a publicly hosted SVG you can embed directly to display the status.

​
Status values

These are the live badgeGraphicUrl graphics. Embed them directly to display the status.
CompliantCompliant: No outstanding issues detected. Balances and filings are in good standing.
At riskAtRisk: An outstanding balance is owed, but no severe issues. 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 fields, and account-level totals read 0.
Not monitoredNotMonitored: TaxRock is not monitoring a business with that EIN for you. 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.

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