---
title: "Estimated-tax / §6654 safe-harbor + underpayment-penalty estimate"
method: POST
path: "/v1/tax/estimated-tax"
tags: ["Tax"]
---

# Estimated-tax / §6654 safe-harbor + underpayment-penalty estimate

`POST /v1/tax/estimated-tax`

## Request

- Base URL: `https://api.numeratica.com`
- URL: `https://api.numeratica.com/v1/tax/estimated-tax`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Evaluates the §6654 estimated-tax safe harbors for an individual and estimates the underpayment penalty if the safe harbor is missed — for anyone with lumpy or under-withheld income (equity comp, business owners, Roth converters). The required annual payment is the lesser of 90% of the current year's tax or the prior-year safe harbor (100% of last year's tax, or 110% when prior-year AGI exceeds $150,000 / $75,000 MFS). No penalty applies if the balance due after withholding is under $1,000, or the prior year had zero tax. The penalty is estimated with the regular method (four equal installments, withholding credited evenly, overpayments carried forward) at the IRS underpayment rate — 7% for 2025 and 2026 by default, overridable per request since the penalty accrues into a year whose quarterly rates are unpublished. Deterministic; not tax advice.

## Request body

- EstimatedTaxRequest
  - `tax_year` integer, required: Current tax year. Must be 2025 or 2026 unless underpayment_rate is supplied.
  - `filing_status` 'single' | 'mfj' | 'mfs' | 'hoh', required
  - `prior_year_tax` number, required: Total tax on the prior-year return (the prior-year safe-harbor base).
  - `prior_year_agi` number, required: Prior-year AGI; over $150,000 ($75,000 MFS) raises the prior-year harbor to 110%.
  - `projected_current_tax` number, required: Expected total tax for the current year.
  - `withholding` number, required: Expected withholding this year (credited evenly across the four installments).
  - `estimated_payments` number[]: The four quarterly estimated payments (Q1..Q4); omit or zero any not yet paid.
  - `underpayment_rate` number: Optional; overrides the assumed annual IRS underpayment rate (e.g. 0.08). Omit to use the year's default (7% for 2025/2026).

## Response `200`

The safe-harbor evaluation and penalty estimate

- EstimatedTaxResponse
  - `result_id` string
  - `engine_version` string
  - `inputs` EstimatedTaxRequest
    - `tax_year` integer, required: Current tax year. Must be 2025 or 2026 unless underpayment_rate is supplied.
    - `filing_status` 'single' | 'mfj' | 'mfs' | 'hoh', required
    - `prior_year_tax` number, required: Total tax on the prior-year return (the prior-year safe-harbor base).
    - `prior_year_agi` number, required: Prior-year AGI; over $150,000 ($75,000 MFS) raises the prior-year harbor to 110%.
    - `projected_current_tax` number, required: Expected total tax for the current year.
    - `withholding` number, required: Expected withholding this year (credited evenly across the four installments).
    - `estimated_payments` number[]: The four quarterly estimated payments (Q1..Q4); omit or zero any not yet paid.
    - `underpayment_rate` number: Optional; overrides the assumed annual IRS underpayment rate (e.g. 0.08). Omit to use the year's default (7% for 2025/2026).
  - `result` object
    - `current_year_safe_harbor` number: 90% of projected current-year tax.
    - `prior_year_safe_harbor` number: 100% or 110% of prior-year tax.
    - `prior_year_multiplier` number: 1.00 or 1.10.
    - `high_income` boolean: Prior-year AGI over the threshold.
    - `required_annual_payment` number: The lesser of the two safe harbors.
    - `governing_safe_harbor` 'current_year_90pct' | 'prior_year': Which safe harbor binds.
    - `total_paid` number: Withholding + all estimated payments.
    - `shortfall` number: max(0, required_annual_payment − total_paid).
    - `safe_harbor_met` boolean
    - `required_quarterly` number: required_annual_payment / 4.
    - `additional_per_quarter_needed` number: Ex-ante even estimated payment (beyond withholding) to reach the safe harbor: (required_annual_payment − withholding) / 4. It assumes no estimated payments yet, so it is not reduced by estimated_payments already made.
    - `de_minimis` boolean: Balance due under $1,000 (§6654(e)(1)).
    - `prior_year_exception` boolean: Prior year had zero tax (§6654(e)(2)).
    - `installments` EstimatedTaxInstallment[]
      - `quarter` integer: 1..4.
      - `due_date` string: MM-DD (the following year for Q4).
      - `required` number: 25% of the required annual payment.
      - `paid` number: withholding/4 + this quarter's estimated payment.
      - `underpaid` number: Running cumulative underpayment (required-to-date − paid-to-date) at this due date; a later payment that catches the account up clears it (§6654(b)(3)).
      - `penalty` number: Running underpayment × rate × this period's days / 365.
      - `cumulative` number: Cumulative required amount through this quarter.
    - `penalty_rate` number: The assumed annual underpayment rate used.
    - `rate_is_default` boolean: True if the year's grounded default was used.
    - `penalty_applies` boolean
    - `estimated_penalty` number: The regular-method penalty estimate.
  - `disclaimer` string

## Other responses

- `400`: Invalid request
- `401`: Missing or invalid API key.
- `405`: Method not allowed
- `429`: The key's per-minute request budget is exceeded. Retry after the delay in the Retry-After header.
- `503`: A dependency (e.g. the key store) is temporarily unavailable, or the request exceeded its compute deadline. Retryable.

---

[API](https://skmtc.dev/numeratica/apis/numeratica-financial-planning-calculations-api.md) · [All operations](https://skmtc.dev/numeratica/apis/numeratica-financial-planning-calculations-api/llms.txt) · [OpenAPI document](https://skmtc.dev/numeratica/apis/numeratica-financial-planning-calculations-api/revisions/075bcfbd1ebf?raw)