Skip to main content
POST
/
client-accounts
/
lookup
/
ein
Look up client account by EIN
curl --request POST \
  --url https://delegate-demo.api.taxrock.com/client-accounts/lookup/ein \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "businessEin": "<string>"
}
'
{
  "currentStatus": {
    "status": "NotCompliant",
    "badgeGraphicUrl": "https://taxrock-assets.s3.us-east-2.amazonaws.com/public/status-badges/taxrock-badge-not-compliant.svg"
  },
  "result": {
    "clientAccountId": "8f3c1e2a-2b44-4c1f-9a0e-1d2c3b4a5e6f",
    "clientAccountName": "Acme Holdings",
    "amountDue": 18452.3,
    "unallocatedCredits": 0,
    "numMissingReturns": 1,
    "taxpayers": [
      {
        "id": "1a2b3c4d-0000-0000-0000-000000000001",
        "name": "Acme Holdings LLC",
        "type": "Business",
        "isLookupMatch": true,
        "tin": "111111111",
        "isTinCensored": false,
        "currentStatus": {
          "status": "NotCompliant",
          "badgeGraphicUrl": "https://taxrock-assets.s3.us-east-2.amazonaws.com/public/status-badges/taxrock-badge-not-compliant.svg"
        },
        "amountDue": 18000,
        "unallocatedCredits": 0,
        "numMissingReturns": 1
      },
      {
        "id": "1a2b3c4d-0000-0000-0000-000000000002",
        "name": "Jane Q Doe",
        "type": "Individual",
        "isLookupMatch": false,
        "tin": "xxxxx6789",
        "isTinCensored": true,
        "currentStatus": {
          "status": "AtRisk",
          "badgeGraphicUrl": "https://taxrock-assets.s3.us-east-2.amazonaws.com/public/status-badges/taxrock-badge-at-risk.svg"
        },
        "amountDue": 452.3,
        "unallocatedCredits": 0,
        "numMissingReturns": 0
      }
    ],
    "pendingTaxpayers": []
  }
}
Looks up the client account containing a business with the given EIN and returns a client-account-wide compliance summary: every taxpayer on the account, plus any not-yet-onboarded pending taxpayers. Returns 200 for any well-formed EIN. result is null and currentStatus.status is NotMonitored when no business with that EIN is accessible to you. A missing or malformed businessEin returns 400.
Status values, badges, tin censoring, and isLookupMatch are described once in Concepts → Compliance status.

​
result fields

  • clientAccountId, clientAccountName — the matched client account.
  • amountDue — total balance owed across the client account.
  • unallocatedCredits — total credits not yet applied to a liability.
  • numMissingReturns — required returns not yet filed, within the recent lookback window.
  • taxpayers[] — each taxpayer on the account, with its own currentStatus (never NotMonitored) and financials. amountDue, unallocatedCredits, and numMissingReturns are null while that taxpayer’s data is pending.
  • pendingTaxpayers[] — taxpayers added to the account but not yet onboarded.
Use the Run panel to try it: paste an access token (see the Quickstart) and send a sandbox EIN such as 11-1111111.

Authorizations

​
Authorization
string
header
required

The access token obtained from the OAuth flow (see Guides → Quickstart). Paste it here to run the endpoint.

Body

application/json
​
businessEin
string
required

Business EIN: nine digits, with dashes and spaces ignored.

Example:

"11-1111111"

Response

Lookup completed. result carries the summary, or is null when nothing matched.

​
currentStatus
object
required

Compliance status plus an embeddable badge graphic. Always present on a response.

​
result
object
required

The client-account summary, or null when nothing matched.