> ## Documentation Index > Fetch the complete documentation index at: https://docs.taxrock.com/llms.txt > Use this file to discover all available pages before exploring further. # Look up client account by EIN > POST /client-accounts/lookup/ein Returns a **client-account-wide** compliance summary for the account containing the given EIN: every taxpayer on the account, plus any not-yet-onboarded pending taxpayers. Each taxpayer carries its own compliance status and detail. `result` is `null` and `currentStatus.status` is `NotMonitored` when no accessible business matches. > [!NOTE] > > Status values, badges, `tin` censoring, and `isLookupMatch` are explained in > [Lookup results](https://docs.taxrock.com/api-reference/lookup-results.md). ## OpenAPI ````yaml api-reference/openapi-delegate.json POST /client-accounts/lookup/ein openapi: 3.1.0 info: title: TaxRock API (delegate access) version: 1.0.0 description: >- The TaxRock API with delegate access: reads what a connected TaxRock user can access, after the user consents once. See Getting started. servers: - url: https://delegate-demo.api.taxrock.com description: Sandbox security: - bearerAuth: [] paths: /client-accounts/lookup/ein: post: tags: - Client Accounts summary: Look up client account by EIN description: >- Looks up the client account containing a business with the given EIN and returns a client-account-wide compliance summary. operationId: lookupClientAccountByEin requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LookupByEinRequest' responses: '200': description: >- Lookup completed. `result` carries the summary, or is null when nothing matched. content: application/json: schema: $ref: '#/components/schemas/ClientAccountLookupResponse' examples: available: summary: Available (data loaded) value: currentStatus: status: NotCompliant badgeGraphicUrl: >- https://taxrock-assets.s3.us-east-2.amazonaws.com/public/status-badges/taxrock-badge-not-compliant.svg badgeGraphicUrlDark: >- https://taxrock-assets.s3.us-east-2.amazonaws.com/public/status-badges/taxrock-badge-not-compliant-dark.svg result: clientAccountId: 8f3c1e2a-2b44-4c1f-9a0e-1d2c3b4a5e6f clientAccountName: Acme Holdings amountDue: 18452.3 unallocatedCredits: 0 numMissingReturns: 1 balanceByYear: - year: 2023 principal: 14000 interest: 2900 penalties: 1552.3 allCredits: 0 unallocatedCredits: 0 amountDue: 18452.3 lienSummary: hasActiveLienSecuringNonZeroBalance: true totalBalanceSecuredByLiens: 18000 mostRecentActiveLienFilingDate: '2024-05-14T00:00:00Z' installmentAgreementSummary: hasBalanceNotCoveredByActiveIA: true balanceNotCoveredByActiveIA: 18000 periodsNotCoveredByActiveIA: - formName: '1120' taxYear: 2023 taxPeriod: 0 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 badgeGraphicUrlDark: >- https://taxrock-assets.s3.us-east-2.amazonaws.com/public/status-badges/taxrock-badge-not-compliant-dark.svg amountDue: 18000 unallocatedCredits: 0 numMissingReturns: 1 balanceByYear: - year: 2023 principal: 14000 interest: 2600 penalties: 1400 allCredits: 0 unallocatedCredits: 0 amountDue: 18000 lienSummary: hasActiveLienSecuringNonZeroBalance: true totalBalanceSecuredByLiens: 18000 mostRecentActiveLienFilingDate: '2024-05-14T00:00:00Z' installmentAgreementSummary: hasBalanceNotCoveredByActiveIA: true balanceNotCoveredByActiveIA: 18000 periodsNotCoveredByActiveIA: - formName: '1120' taxYear: 2023 taxPeriod: 0 liens: - id: 3c4d5e6f-0000-0000-0000-000000000001 status: Active filingDate: '2024-05-14T00:00:00Z' currentSecuredBalance: 18000 securedPeriods: - formName: '1120' taxYear: 2023 taxPeriod: 0 fullyRemovedDate: null balanceAtRemoval: null installmentAgreements: [] - id: 1a2b3c4d-0000-0000-0000-000000000002 name: Jane Q Doe type: Individual isLookupMatch: false tin: xxxxx0000 isTinCensored: true currentStatus: status: AtRisk badgeGraphicUrl: >- https://taxrock-assets.s3.us-east-2.amazonaws.com/public/status-badges/taxrock-badge-at-risk.svg badgeGraphicUrlDark: >- https://taxrock-assets.s3.us-east-2.amazonaws.com/public/status-badges/taxrock-badge-at-risk-dark.svg amountDue: 452.3 unallocatedCredits: 0 numMissingReturns: 0 balanceByYear: - year: 2023 principal: 400 interest: 40 penalties: 12.3 allCredits: 0 unallocatedCredits: 0 amountDue: 452.3 lienSummary: hasActiveLienSecuringNonZeroBalance: false totalBalanceSecuredByLiens: 0 mostRecentActiveLienFilingDate: null installmentAgreementSummary: hasBalanceNotCoveredByActiveIA: false balanceNotCoveredByActiveIA: 0 periodsNotCoveredByActiveIA: [] liens: [] installmentAgreements: - id: 4d5e6f70-0000-0000-0000-000000000001 status: Active startDate: '2024-02-01T00:00:00Z' endDate: null currentBalance: 452.3 balanceAtClose: null totalPaid: 300 coveredPeriods: - formName: '1040' taxYear: 2023 taxPeriod: 0 pendingTaxpayers: [] dataPending: summary: Matched, data not ready value: currentStatus: status: DataPending badgeGraphicUrl: >- https://taxrock-assets.s3.us-east-2.amazonaws.com/public/status-badges/taxrock-badge-data-pending.svg badgeGraphicUrlDark: >- https://taxrock-assets.s3.us-east-2.amazonaws.com/public/status-badges/taxrock-badge-data-pending-dark.svg result: clientAccountId: 7e6d5c4b-3a29-4817-8c6d-5e4f3a2b1c09 clientAccountName: Newco Ventures amountDue: 0 unallocatedCredits: 0 numMissingReturns: 0 balanceByYear: [] lienSummary: hasActiveLienSecuringNonZeroBalance: false totalBalanceSecuredByLiens: 0 mostRecentActiveLienFilingDate: null installmentAgreementSummary: hasBalanceNotCoveredByActiveIA: false balanceNotCoveredByActiveIA: 0 periodsNotCoveredByActiveIA: [] taxpayers: - id: 2b3c4d5e-0000-0000-0000-000000000001 name: Newco Ventures Inc type: Business isLookupMatch: true tin: '000000000' isTinCensored: false currentStatus: status: DataPending badgeGraphicUrl: >- https://taxrock-assets.s3.us-east-2.amazonaws.com/public/status-badges/taxrock-badge-data-pending.svg badgeGraphicUrlDark: >- https://taxrock-assets.s3.us-east-2.amazonaws.com/public/status-badges/taxrock-badge-data-pending-dark.svg amountDue: null unallocatedCredits: null numMissingReturns: null balanceByYear: [] lienSummary: hasActiveLienSecuringNonZeroBalance: false totalBalanceSecuredByLiens: 0 mostRecentActiveLienFilingDate: null installmentAgreementSummary: hasBalanceNotCoveredByActiveIA: false balanceNotCoveredByActiveIA: 0 periodsNotCoveredByActiveIA: [] liens: [] installmentAgreements: [] pendingTaxpayers: - id: 2b3c4d5e-0000-0000-0000-000000000002 name: Side Co LLC type: Business isLookupMatch: false tin: '000000000' isTinCensored: false notMonitored: summary: Not monitored (no taxpayer with that EIN) value: currentStatus: status: NotMonitored badgeGraphicUrl: >- https://taxrock-assets.s3.us-east-2.amazonaws.com/public/status-badges/taxrock-badge-not-monitored.svg badgeGraphicUrlDark: >- https://taxrock-assets.s3.us-east-2.amazonaws.com/public/status-badges/taxrock-badge-not-monitored-dark.svg result: null '400': description: >- The `businessEin` was missing or malformed, or the request body could not be read. content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: invalidEin: summary: Malformed EIN value: error: invalid_ein message: >- businessEin must contain nine digits; dashes and spaces are ignored. invalidRequest: summary: Missing or non-string EIN value: error: invalid_request message: A non-empty businessEin string is required. malformedBody: summary: Unparseable request body value: error: invalid_request message: Request body is invalid or malformed JSON. '401': description: >- Missing or invalid access token. Refresh the token, or send the user back through the authorization flow. '403': description: >- `error` is `insufficient_scope` when the token lacks the `read:client-accounts` scope, or `forbidden` when the connected user is not eligible or lacks permission. content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: insufficientScope: summary: Token missing the required scope value: error: insufficient_scope message: >- Access token is missing the required scope. Re-run authorize requesting: read:client-accounts. forbidden: summary: User not eligible or not permitted value: error: forbidden message: Caller lacks the required permission. components: schemas: LookupByEinRequest: type: object required: - businessEin properties: businessEin: type: string description: 'Business EIN: nine digits, with dashes and spaces ignored.' examples: - 11-1111111 ClientAccountLookupResponse: type: object required: - currentStatus - result properties: currentStatus: $ref: '#/components/schemas/CurrentStatus' result: anyOf: - $ref: '#/components/schemas/ClientAccountSummary' - type: 'null' description: The client-account summary, or null when nothing matched. ApiError: type: object required: - error - message properties: error: type: string description: Machine-readable error code, e.g. `invalid_request` or `forbidden`. message: type: string description: Human-readable explanation. CurrentStatus: type: object required: - status - badgeGraphicUrl - badgeGraphicUrlDark description: >- Compliance status plus embeddable badge graphics. Always present on a response. properties: status: type: string enum: - NotMonitored - DataPending - Compliant - ActiveResolution - AtRisk - NotCompliant description: See the Lookup results page for the full meaning of each value. badgeGraphicUrl: type: string format: uri description: Publicly hosted SVG badge for this status, for light backgrounds. badgeGraphicUrlDark: type: string format: uri description: >- Publicly hosted SVG badge for this status, tuned for dark backgrounds. ClientAccountSummary: type: object required: - clientAccountId - clientAccountName - amountDue - unallocatedCredits - numMissingReturns - balanceByYear - lienSummary - installmentAgreementSummary - taxpayers - pendingTaxpayers properties: clientAccountId: type: string format: uuid clientAccountName: type: string amountDue: type: number description: Total balance owed across the client account. unallocatedCredits: type: number description: Total credits not yet applied to a liability. numMissingReturns: type: integer description: Number of required tax returns that are past due and not filed. balanceByYear: type: array items: $ref: '#/components/schemas/BalanceByYear' description: >- Per-tax-year balance breakdown aggregated across the account's taxpayers, most recent year first. lienSummary: $ref: '#/components/schemas/LienSummary' installmentAgreementSummary: $ref: '#/components/schemas/InstallmentAgreementSummary' taxpayers: type: array items: $ref: '#/components/schemas/ClientAccountTaxpayer' pendingTaxpayers: type: array items: $ref: '#/components/schemas/PendingTaxpayer' BalanceByYear: type: object required: - year - principal - interest - penalties - allCredits - unallocatedCredits - amountDue description: Balance breakdown for a single tax year. properties: year: type: integer principal: type: number interest: type: number penalties: type: number allCredits: type: number description: All credits applied for the year. unallocatedCredits: type: number description: Credits not yet applied to a liability. amountDue: type: number description: Net balance owed for the year. LienSummary: type: object required: - hasActiveLienSecuringNonZeroBalance - totalBalanceSecuredByLiens - mostRecentActiveLienFilingDate description: Lien rollups for a taxpayer or client account. properties: hasActiveLienSecuringNonZeroBalance: type: boolean description: True when at least one active lien secures a balance above zero. totalBalanceSecuredByLiens: type: number description: Total balance currently secured across active liens. mostRecentActiveLienFilingDate: type: - string - 'null' format: date-time description: >- Filing date of the most recently filed active lien; null when there are none. InstallmentAgreementSummary: type: object required: - hasBalanceNotCoveredByActiveIA - balanceNotCoveredByActiveIA - periodsNotCoveredByActiveIA description: Installment-agreement rollups for a taxpayer or client account. properties: hasBalanceNotCoveredByActiveIA: type: boolean description: >- True when a balance is owed that no active installment agreement covers. balanceNotCoveredByActiveIA: type: number description: Total balance not covered by an active installment agreement. periodsNotCoveredByActiveIA: type: array items: $ref: '#/components/schemas/FormPeriod' description: >- Periods with a balance not covered by an active installment agreement. ClientAccountTaxpayer: type: object required: - id - name - type - isLookupMatch - tin - isTinCensored - currentStatus - amountDue - unallocatedCredits - numMissingReturns - balanceByYear - lienSummary - installmentAgreementSummary - liens - installmentAgreements properties: id: type: string format: uuid name: type: string type: $ref: '#/components/schemas/TaxpayerType' isLookupMatch: type: boolean description: True on the row whose TIN matched the EIN you looked up. tin: type: - string - 'null' description: >- Unformatted digits. Raw nine-digit EIN for businesses, censored to the last four (xxxxx0123) for individuals. isTinCensored: type: boolean description: True when `tin` is censored. currentStatus: $ref: '#/components/schemas/CurrentStatus' amountDue: type: - number - 'null' description: Null while this taxpayer's data is pending. unallocatedCredits: type: - number - 'null' description: Null while this taxpayer's data is pending. numMissingReturns: type: - integer - 'null' description: >- Number of required tax returns that are past due and not filed. Null while data is pending. balanceByYear: type: array items: $ref: '#/components/schemas/BalanceByYear' description: >- Per-tax-year balance breakdown for this taxpayer, most recent year first. lienSummary: $ref: '#/components/schemas/LienSummary' installmentAgreementSummary: $ref: '#/components/schemas/InstallmentAgreementSummary' liens: type: array items: $ref: '#/components/schemas/Lien' description: All liens on the taxpayer, any status. installmentAgreements: type: array items: $ref: '#/components/schemas/InstallmentAgreement' description: All installment agreements on the taxpayer, any status. PendingTaxpayer: type: object required: - id - name - type - isLookupMatch - tin - isTinCensored description: A taxpayer added to the client account but not yet onboarded. properties: id: type: string format: uuid name: type: string type: $ref: '#/components/schemas/TaxpayerType' isLookupMatch: type: boolean tin: type: - string - 'null' description: Null if not provided yet. isTinCensored: type: boolean FormPeriod: type: object required: - formName - taxYear - taxPeriod description: A single tax form and period. properties: formName: type: string description: IRS form name, e.g. "1120" or "941". taxYear: type: integer taxPeriod: type: integer description: The tax period within the tax year. TaxpayerType: type: string enum: - Business - Individual description: Whether the taxpayer is a business (EIN) or an individual (SSN). Lien: type: object required: - id - status - filingDate - currentSecuredBalance - securedPeriods - fullyRemovedDate - balanceAtRemoval description: A federal tax lien on the taxpayer. properties: id: type: string format: uuid status: $ref: '#/components/schemas/LienStatus' filingDate: type: string format: date-time currentSecuredBalance: type: number description: Balance currently secured by this lien. securedPeriods: type: array items: $ref: '#/components/schemas/FormPeriod' description: Periods still securing a balance under this lien. fullyRemovedDate: type: - string - 'null' format: date-time description: When the lien was fully removed; null while active. balanceAtRemoval: type: - number - 'null' description: Secured balance at the time of removal; null while active. InstallmentAgreement: type: object required: - id - status - startDate - endDate - currentBalance - balanceAtClose - totalPaid - coveredPeriods description: An installment agreement on the taxpayer. properties: id: type: string format: uuid status: $ref: '#/components/schemas/InstallmentAgreementStatus' startDate: type: string format: date-time endDate: type: - string - 'null' format: date-time description: When the agreement ended; null while open. currentBalance: type: number description: Balance remaining under the agreement. balanceAtClose: type: - number - 'null' description: Balance when the agreement closed; null while open. totalPaid: type: number description: Total paid toward the agreement to date. coveredPeriods: type: array items: $ref: '#/components/schemas/FormPeriod' description: Periods currently covered by this agreement. LienStatus: type: string enum: - Active - Released - Removed description: Lien lifecycle state. InstallmentAgreementStatus: type: string enum: - Requested - Pending - Active - PaidOff - Defaulted - Removed description: Installment-agreement lifecycle state. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- The access token obtained from the OAuth flow, sent as a Bearer credential. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.