Skip to main content
Both lookup endpoints return a currentStatus object and identify taxpayers with the same conventions. They’re described once here.

​
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. Financial fields are null.
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

On the client-account lookup, the top-level currentStatus is client-account-wide: 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 — 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 — no status or financial fields.

​
Errors

A missing or malformed businessEin returns 400 with an { error, message } body:
  • invalid_request — businessEin was absent or not a string.
  • invalid_ein — businessEin did not contain nine digits (dashes and spaces are ignored).