{
    "openapi": "3.1.0",
    "info": {
        "title": "GetNetWage paycheck API",
        "version": "1.0.0",
        "summary": "Take-home pay after 2026 federal, FICA and state taxes for any US wage or salary.",
        "description": "Read-only JSON API with the same 2026 tax tables as getnetwage.com. Figures are annual tax liability for a resident with no dependents, credits or other income, spread evenly over the year; local income taxes are not included. No key; CORS enabled; 60 requests a minute per IP address. Please link to the page given in `page` (or to https://getnetwage.com/) when you show a result.",
        "contact": {
            "name": "GetNetWage",
            "url": "https://getnetwage.com/contact/",
            "email": "pablobravo44@gmail.com"
        },
        "license": {
            "name": "Free with attribution",
            "url": "https://getnetwage.com/terms/"
        }
    },
    "servers": [
        {
            "url": "https://getnetwage.com",
            "description": "Production"
        }
    ],
    "externalDocs": {
        "description": "API documentation",
        "url": "https://getnetwage.com/api/"
    },
    "tags": [
        {
            "name": "paycheck",
            "description": "Take-home pay calculations"
        }
    ],
    "paths": {
        "/api/v1/paycheck": {
            "get": {
                "operationId": "getPaycheck",
                "tags": [
                    "paycheck"
                ],
                "summary": "Take-home pay for a wage or salary",
                "description": "Pass `wage` (hourly) or `salary` (yearly); if both are given, `salary` is used. Returns every tax line for the year, per-period and per-paycheck amounts, and the matching static page when one exists.",
                "parameters": [
                    {
                        "name": "wage",
                        "in": "query",
                        "required": false,
                        "description": "Hourly wage in dollars. \"25\", \"25.50\" and \"$25\" are accepted. Required unless `salary` is given.",
                        "schema": {
                            "type": "number",
                            "minimum": 0.01,
                            "maximum": 1000
                        },
                        "example": 25
                    },
                    {
                        "name": "salary",
                        "in": "query",
                        "required": false,
                        "description": "Yearly salary in dollars. \"60000\", \"60,000\" and \"60k\" are accepted. Required unless `wage` is given.",
                        "schema": {
                            "type": "number",
                            "minimum": 1,
                            "maximum": 5000000
                        },
                        "example": 60000
                    },
                    {
                        "name": "state",
                        "in": "query",
                        "required": false,
                        "description": "State as a two-letter code, name or slug (TX, Texas, new-york), for the 50 states and DC. Omit, or pass \"none\", for federal and FICA only.",
                        "schema": {
                            "type": "string"
                        },
                        "example": "TX"
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "description": "Filing status. married_joint assumes one earner.",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "single",
                                "married_joint",
                                "head_of_household"
                            ],
                            "default": "single"
                        }
                    },
                    {
                        "name": "hours",
                        "in": "query",
                        "required": false,
                        "description": "Hours worked a week. For hourly pay, hours over 40 are paid at 1.5 times; salaries ignore it.",
                        "schema": {
                            "type": "number",
                            "minimum": 1,
                            "maximum": 100,
                            "default": 40
                        }
                    },
                    {
                        "name": "frequency",
                        "in": "query",
                        "required": false,
                        "description": "Pay frequency for annual-liability averages and the health premium. Invalid values return an error.",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "weekly",
                                "biweekly",
                                "semimonthly",
                                "monthly"
                            ],
                            "default": "biweekly"
                        }
                    },
                    {
                        "name": "k401",
                        "in": "query",
                        "required": false,
                        "description": "Employee 401(k) contribution, percent of gross pay, capped at the annual limit.",
                        "schema": {
                            "type": "number",
                            "minimum": 0,
                            "maximum": 75,
                            "default": 0
                        }
                    },
                    {
                        "name": "health",
                        "in": "query",
                        "required": false,
                        "description": "Pre-tax (section 125) health premium per paycheck, in dollars.",
                        "schema": {
                            "type": "number",
                            "minimum": 0,
                            "maximum": 10000,
                            "default": 0
                        }
                    },
                    {
                        "name": "weeks",
                        "in": "query",
                        "required": false,
                        "description": "Paid weeks for hourly earnings; salary is actual annual pay.",
                        "schema": {
                            "type": "number",
                            "minimum": 1,
                            "maximum": 52,
                            "default": 52
                        }
                    },
                    {
                        "name": "overtime",
                        "in": "query",
                        "required": false,
                        "description": "Qualified FLSA premium eligibility; reported premium is already included in gross pay.",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "flsa",
                                "none",
                                "reported"
                            ],
                            "default": "flsa"
                        }
                    },
                    {
                        "name": "qualified_premium",
                        "in": "query",
                        "required": false,
                        "description": "Annual qualified premium when overtime=reported.",
                        "schema": {
                            "type": "number",
                            "minimum": 0,
                            "maximum": 5000000
                        }
                    },
                    {
                        "name": "k401_age",
                        "in": "query",
                        "required": false,
                        "description": "Age band and confirmed plan catch-up eligibility.",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "under50",
                                "50plus",
                                "60to63"
                            ],
                            "default": "under50"
                        }
                    },
                    {
                        "name": "k401_already",
                        "in": "query",
                        "required": false,
                        "description": "Employee deferrals elsewhere; reduces the available annual limit. Other earnings excluded.",
                        "schema": {
                            "type": "number",
                            "minimum": 0,
                            "maximum": 35750,
                            "default": 0
                        }
                    },
                    {
                        "name": "k401_type",
                        "in": "query",
                        "required": false,
                        "description": "Elective deferral tax treatment.",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "pretax",
                                "roth"
                            ],
                            "default": "pretax"
                        }
                    },
                    {
                        "name": "catchup_tax",
                        "in": "query",
                        "required": false,
                        "description": "Roth by default; pretax requires confirmed plan eligibility and prior-employer wages threshold.",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "roth",
                                "pretax"
                            ],
                            "default": "roth"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Take-home pay",
                        "headers": {
                            "X-RateLimit-Limit": {
                                "description": "Requests allowed per minute",
                                "schema": {
                                    "type": "integer"
                                }
                            },
                            "X-RateLimit-Remaining": {
                                "description": "Requests left in the current minute",
                                "schema": {
                                    "type": "integer"
                                }
                            },
                            "X-RateLimit-Reset": {
                                "description": "Unix time when the current window ends",
                                "schema": {
                                    "type": "integer"
                                }
                            },
                            "Access-Control-Allow-Origin": {
                                "schema": {
                                    "type": "string",
                                    "const": "*"
                                }
                            }
                        },
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PaycheckResponse"
                                },
                                "example": {
                                    "tax_year": 2026,
                                    "input": {
                                        "mode": "hourly",
                                        "amount": 25,
                                        "hours_per_week": 40,
                                        "state": "TX",
                                        "status": "single",
                                        "frequency": "biweekly",
                                        "k401_percent": 0,
                                        "health_per_paycheck": 0
                                    },
                                    "result": {
                                        "annual": {
                                            "gross": 52000,
                                            "pretax_401k": 0,
                                            "roth_401k": 0,
                                            "pretax_health": 0,
                                            "federal_taxable": 35900,
                                            "federal_income_tax": 4060,
                                            "overtime_deduction": 0,
                                            "social_security": 3224,
                                            "medicare": 754,
                                            "state_income_tax": 0,
                                            "state_payroll": [],
                                            "total_tax": 8038,
                                            "net": 43962
                                        },
                                        "retirement": {
                                            "requested": 0,
                                            "limit": 24500,
                                            "available": 24500,
                                            "total": 0,
                                            "pretax": 0,
                                            "roth": 0,
                                            "capped": false
                                        },
                                        "per_period": {
                                            "year": {
                                                "gross": 52000,
                                                "total_tax": 8038,
                                                "net": 43962
                                            },
                                            "month": {
                                                "gross": 4333.33,
                                                "total_tax": 669.83,
                                                "net": 3663.5
                                            },
                                            "biweekly": {
                                                "gross": 2000,
                                                "total_tax": 309.15,
                                                "net": 1690.85
                                            },
                                            "semimonthly": {
                                                "gross": 2166.67,
                                                "total_tax": 334.92,
                                                "net": 1831.75
                                            },
                                            "week": {
                                                "gross": 1000,
                                                "total_tax": 154.58,
                                                "net": 845.42
                                            },
                                            "day": {
                                                "gross": 200,
                                                "total_tax": 30.92,
                                                "net": 169.08
                                            }
                                        },
                                        "per_paycheck": {
                                            "frequency": "biweekly",
                                            "net": 1690.85,
                                            "gross": 2000
                                        },
                                        "effective_rate": 0.1546,
                                        "federal_marginal_rate": 0.12,
                                        "state_marginal_rate": 0
                                    },
                                    "assumptions": "Annual liability, no dependents or credits, no other income, local taxes excluded. See https://getnetwage.com/methodology/",
                                    "page": "https://getnetwage.com/hourly/25-an-hour/texas/",
                                    "data_retrieved_at": "2026-09-26",
                                    "attribution": "GetNetWage https://getnetwage.com/"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "`missing_parameter` when neither wage nor salary is given; `invalid_parameter` with a message per field otherwise",
                        "headers": {
                            "X-RateLimit-Limit": {
                                "description": "Requests allowed per minute",
                                "schema": {
                                    "type": "integer"
                                }
                            },
                            "X-RateLimit-Remaining": {
                                "description": "Requests left in the current minute",
                                "schema": {
                                    "type": "integer"
                                }
                            },
                            "X-RateLimit-Reset": {
                                "description": "Unix time when the current window ends",
                                "schema": {
                                    "type": "integer"
                                }
                            }
                        },
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "More than 60 requests in a minute from one IP address",
                        "headers": {
                            "X-RateLimit-Limit": {
                                "description": "Requests allowed per minute",
                                "schema": {
                                    "type": "integer"
                                }
                            },
                            "X-RateLimit-Remaining": {
                                "description": "Requests left in the current minute",
                                "schema": {
                                    "type": "integer"
                                }
                            },
                            "X-RateLimit-Reset": {
                                "description": "Unix time when the current window ends",
                                "schema": {
                                    "type": "integer"
                                }
                            },
                            "Retry-After": {
                                "description": "Seconds until the limit resets",
                                "schema": {
                                    "type": "integer"
                                }
                            }
                        },
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "PaycheckResponse": {
                "type": "object",
                "required": [
                    "tax_year",
                    "input",
                    "result",
                    "assumptions",
                    "page",
                    "data_retrieved_at",
                    "attribution"
                ],
                "properties": {
                    "tax_year": {
                        "type": "integer",
                        "description": "Tax year of the tables used"
                    },
                    "input": {
                        "type": "object",
                        "description": "The inputs as understood after validation",
                        "properties": {
                            "mode": {
                                "type": "string",
                                "enum": [
                                    "hourly",
                                    "salary"
                                ]
                            },
                            "amount": {
                                "type": "number"
                            },
                            "hours_per_week": {
                                "type": "number"
                            },
                            "state": {
                                "type": [
                                    "string",
                                    "null"
                                ],
                                "description": "Two-letter code, or null for federal and FICA only"
                            },
                            "status": {
                                "type": "string",
                                "enum": [
                                    "single",
                                    "married_joint",
                                    "head_of_household"
                                ]
                            },
                            "frequency": {
                                "type": "string",
                                "enum": [
                                    "weekly",
                                    "biweekly",
                                    "semimonthly",
                                    "monthly"
                                ]
                            },
                            "k401_percent": {
                                "type": "number"
                            },
                            "health_per_paycheck": {
                                "type": "number"
                            }
                        }
                    },
                    "result": {
                        "type": "object",
                        "properties": {
                            "annual": {
                                "type": "object",
                                "properties": {
                                    "gross": {
                                        "type": "number",
                                        "description": "US dollars, rounded to cents"
                                    },
                                    "pretax_401k": {
                                        "type": "number",
                                        "description": "US dollars, rounded to cents"
                                    },
                                    "pretax_health": {
                                        "type": "number",
                                        "description": "US dollars, rounded to cents"
                                    },
                                    "federal_taxable": {
                                        "type": "number",
                                        "description": "US dollars, rounded to cents"
                                    },
                                    "federal_income_tax": {
                                        "type": "number",
                                        "description": "US dollars, rounded to cents"
                                    },
                                    "overtime_deduction": {
                                        "type": "number",
                                        "description": "US dollars, rounded to cents"
                                    },
                                    "social_security": {
                                        "type": "number",
                                        "description": "US dollars, rounded to cents"
                                    },
                                    "medicare": {
                                        "type": "number",
                                        "description": "US dollars, rounded to cents"
                                    },
                                    "state_income_tax": {
                                        "type": "number",
                                        "description": "US dollars, rounded to cents"
                                    },
                                    "state_payroll": {
                                        "type": "array",
                                        "description": "Required employee state payroll contributions (disability, paid leave, unemployment, long-term care)",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "name": {
                                                    "type": "string"
                                                },
                                                "amount": {
                                                    "type": "number",
                                                    "description": "US dollars, rounded to cents"
                                                }
                                            }
                                        }
                                    },
                                    "total_tax": {
                                        "type": "number",
                                        "description": "US dollars, rounded to cents"
                                    },
                                    "net": {
                                        "type": "number",
                                        "description": "US dollars, rounded to cents"
                                    }
                                }
                            },
                            "per_period": {
                                "type": "object",
                                "description": "The year divided evenly: 12 months, 26 biweekly periods, 52 weeks, 260 working days",
                                "properties": {
                                    "year": {
                                        "type": "object",
                                        "required": [
                                            "gross",
                                            "total_tax",
                                            "net"
                                        ],
                                        "properties": {
                                            "gross": {
                                                "type": "number",
                                                "description": "US dollars, rounded to cents"
                                            },
                                            "total_tax": {
                                                "type": "number",
                                                "description": "US dollars, rounded to cents"
                                            },
                                            "net": {
                                                "type": "number",
                                                "description": "US dollars, rounded to cents"
                                            }
                                        }
                                    },
                                    "month": {
                                        "type": "object",
                                        "required": [
                                            "gross",
                                            "total_tax",
                                            "net"
                                        ],
                                        "properties": {
                                            "gross": {
                                                "type": "number",
                                                "description": "US dollars, rounded to cents"
                                            },
                                            "total_tax": {
                                                "type": "number",
                                                "description": "US dollars, rounded to cents"
                                            },
                                            "net": {
                                                "type": "number",
                                                "description": "US dollars, rounded to cents"
                                            }
                                        }
                                    },
                                    "biweekly": {
                                        "type": "object",
                                        "required": [
                                            "gross",
                                            "total_tax",
                                            "net"
                                        ],
                                        "properties": {
                                            "gross": {
                                                "type": "number",
                                                "description": "US dollars, rounded to cents"
                                            },
                                            "total_tax": {
                                                "type": "number",
                                                "description": "US dollars, rounded to cents"
                                            },
                                            "net": {
                                                "type": "number",
                                                "description": "US dollars, rounded to cents"
                                            }
                                        }
                                    },
                                    "semimonthly": {
                                        "type": "object",
                                        "required": [
                                            "gross",
                                            "total_tax",
                                            "net"
                                        ],
                                        "properties": {
                                            "gross": {
                                                "type": "number",
                                                "description": "US dollars, rounded to cents"
                                            },
                                            "total_tax": {
                                                "type": "number",
                                                "description": "US dollars, rounded to cents"
                                            },
                                            "net": {
                                                "type": "number",
                                                "description": "US dollars, rounded to cents"
                                            }
                                        }
                                    },
                                    "week": {
                                        "type": "object",
                                        "required": [
                                            "gross",
                                            "total_tax",
                                            "net"
                                        ],
                                        "properties": {
                                            "gross": {
                                                "type": "number",
                                                "description": "US dollars, rounded to cents"
                                            },
                                            "total_tax": {
                                                "type": "number",
                                                "description": "US dollars, rounded to cents"
                                            },
                                            "net": {
                                                "type": "number",
                                                "description": "US dollars, rounded to cents"
                                            }
                                        }
                                    },
                                    "day": {
                                        "type": "object",
                                        "required": [
                                            "gross",
                                            "total_tax",
                                            "net"
                                        ],
                                        "properties": {
                                            "gross": {
                                                "type": "number",
                                                "description": "US dollars, rounded to cents"
                                            },
                                            "total_tax": {
                                                "type": "number",
                                                "description": "US dollars, rounded to cents"
                                            },
                                            "net": {
                                                "type": "number",
                                                "description": "US dollars, rounded to cents"
                                            }
                                        }
                                    }
                                }
                            },
                            "per_paycheck": {
                                "type": "object",
                                "properties": {
                                    "frequency": {
                                        "type": "string",
                                        "enum": [
                                            "weekly",
                                            "biweekly",
                                            "semimonthly",
                                            "monthly"
                                        ]
                                    },
                                    "net": {
                                        "type": "number",
                                        "description": "US dollars, rounded to cents"
                                    },
                                    "gross": {
                                        "type": "number",
                                        "description": "US dollars, rounded to cents"
                                    }
                                }
                            },
                            "effective_rate": {
                                "type": "number",
                                "description": "total_tax / gross, as a decimal"
                            },
                            "federal_marginal_rate": {
                                "type": "number",
                                "description": "Federal rate on the last dollar, as a decimal"
                            },
                            "state_marginal_rate": {
                                "type": "number",
                                "description": "State rate on the last dollar, as a decimal"
                            }
                        }
                    },
                    "assumptions": {
                        "type": "string"
                    },
                    "page": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "uri",
                        "description": "The matching static page (40 hours, single, no pre-tax deductions, amount in the page set), or null"
                    },
                    "data_retrieved_at": {
                        "type": "string",
                        "format": "date"
                    },
                    "attribution": {
                        "type": "string"
                    }
                }
            },
            "Error": {
                "type": "object",
                "required": [
                    "error"
                ],
                "properties": {
                    "error": {
                        "type": "string",
                        "enum": [
                            "missing_parameter",
                            "invalid_parameter",
                            "rate_limited"
                        ]
                    },
                    "message": {
                        "type": "string"
                    },
                    "fields": {
                        "type": "object",
                        "additionalProperties": {
                            "type": "string"
                        },
                        "description": "Parameter name to error message"
                    }
                }
            }
        }
    }
}