---
title: "IRA deductibility & Roth contribution eligibility by MAGI"
method: POST
path: "/v1/ira-eligibility"
tags: ["Utilities"]
---

# IRA deductibility & Roth contribution eligibility by MAGI

`POST /v1/ira-eligibility`

## Request

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

Determines how much of an IRA contribution is tax-deductible (traditional) and how much can be contributed to a Roth, by applying the IRS MAGI phase-out ranges for the filing status. Traditional deductibility depends on whether the contributor (or spouse) is an active participant in a workplace plan. Reuses the contribution-limits engine for the IRA dollar figure. Year-keyed IRS tables. Deterministic.

## Request body

- IRAEligibilityRequest
  - `tax_year` 2025 | 2026, required
  - `filing_status` 'single' | 'mfj' | 'mfs' | 'hoh', required
  - `magi` number, required: Modified adjusted gross income.
  - `age` integer, required: Sets the catch-up portion of the IRA limit.
  - `covered_by_workplace_plan` boolean: Whether the contributor is an active participant in an employer plan.
  - `spouse_covered` boolean: Relevant when the contributor is not covered but files jointly/separately with a covered spouse.
  - `compensation` number: Optional. Caps the contribution at earned income.
  - `elective_deferral` number: Optional. 401(k) deferral this year, for mega-backdoor capacity.
  - `employer_contributions` number: Optional. Employer 401(k) contributions, for mega-backdoor capacity.
  - `plan_allows_mega_backdoor` boolean: Whether the plan permits after-tax contributions + in-plan Roth conversion.

## Response `200`

IRA eligibility

- IRAEligibilityResponse
  - `result_id` string
  - `engine_version` string
  - `inputs` IRAEligibilityRequest
    - `tax_year` 2025 | 2026, required
    - `filing_status` 'single' | 'mfj' | 'mfs' | 'hoh', required
    - `magi` number, required: Modified adjusted gross income.
    - `age` integer, required: Sets the catch-up portion of the IRA limit.
    - `covered_by_workplace_plan` boolean: Whether the contributor is an active participant in an employer plan.
    - `spouse_covered` boolean: Relevant when the contributor is not covered but files jointly/separately with a covered spouse.
    - `compensation` number: Optional. Caps the contribution at earned income.
    - `elective_deferral` number: Optional. 401(k) deferral this year, for mega-backdoor capacity.
    - `employer_contributions` number: Optional. Employer 401(k) contributions, for mega-backdoor capacity.
    - `plan_allows_mega_backdoor` boolean: Whether the plan permits after-tax contributions + in-plan Roth conversion.
  - `result` object
    - `ira_limit` number: Base + age-50 catch-up, capped at compensation.
    - `traditional_deductible` EligibilityLine
      - `status` 'full' | 'partial' | 'none'
      - `amount` number: Deductible (traditional) or allowed (Roth) dollars.
      - `phase_out_low` number: 0 if no phase-out applies.
      - `phase_out_high` number: 0 if no phase-out applies.
    - `roth_contribution` EligibilityLine
      - `status` 'full' | 'partial' | 'none'
      - `amount` number: Deductible (traditional) or allowed (Roth) dollars.
      - `phase_out_low` number: 0 if no phase-out applies.
      - `phase_out_high` number: 0 if no phase-out applies.
    - `backdoor_roth_applicable` boolean: Direct Roth is income-restricted, so the nondeductible-trad-IRA + conversion route applies.
    - `mega_backdoor_capacity` number: After-tax 401(k) space (§415(c) − deferral − employer); 0 unless the plan permits it.
  - `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)