> ## 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 taxpayer by EIN > POST /taxpayers/lookup/ein Returns a single business taxpayer's compliance summary. This is the single-taxpayer counterpart to the [client-account lookup](https://docs.taxrock.com/delegate-access/api-reference/client-accounts/lookup-by-ein.md). `result` is `null` when no accessible business matches the EIN. > [!NOTE] > > Status values and badges are explained in > [Lookup results](https://docs.taxrock.com/api-reference/lookup-results.md). ## OpenAPI ````yaml api-reference/openapi-delegate.json POST /taxpayers/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: /taxpayers/lookup/ein: post: tags: - Taxpayers summary: Look up taxpayer by EIN description: >- Looks up the single business taxpayer with the given EIN and returns its compliance summary. operationId: lookupTaxpayerByEin requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LookupByEinRequest' responses: '200': description: >- Lookup completed. `result` carries the taxpayer summary, or is null when nothing matched. content: application/json: schema: $ref: '#/components/schemas/TaxpayerLookupResponse' 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: id: 1a2b3c4d-0000-0000-0000-000000000001 name: Acme Holdings LLC type: Business tin: '111111111' isTinCensored: false 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: [] 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: id: 2b3c4d5e-0000-0000-0000-000000000002 name: Side Co LLC type: Business tin: '000000000' isTinCensored: false amountDue: null unallocatedCredits: null numMissingReturns: null balanceByYear: [] lienSummary: hasActiveLienSecuringNonZeroBalance: false totalBalanceSecuredByLiens: 0 mostRecentActiveLienFilingDate: null installmentAgreementSummary: hasBalanceNotCoveredByActiveIA: false balanceNotCoveredByActiveIA: 0 periodsNotCoveredByActiveIA: [] liens: [] installmentAgreements: [] 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 TaxpayerLookupResponse: type: object required: - currentStatus - result properties: currentStatus: $ref: '#/components/schemas/CurrentStatus' result: anyOf: - $ref: '#/components/schemas/TaxpayerSummary' - type: 'null' description: The taxpayer 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. TaxpayerSummary: type: object required: - id - name - type - tin - isTinCensored - amountDue - unallocatedCredits - numMissingReturns - balanceByYear - lienSummary - installmentAgreementSummary - liens - installmentAgreements properties: id: type: string format: uuid name: type: string type: type: string enum: - Business description: Always Business for EIN lookups. tin: type: - string - 'null' description: >- The business EIN, unformatted nine digits. Not censored on this endpoint. isTinCensored: type: boolean description: Always false on this endpoint. amountDue: type: - number - 'null' description: Null while data is pending. unallocatedCredits: type: - number - 'null' description: Null while 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. 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. 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. 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. 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.