{
    "openapi": "3.1.0",
    "info": {
        "title": "Net Salary World API",
        "version": "1.0.0",
        "summary": "Net salary after income tax and social contributions, country by country.",
        "description": "Read-only JSON API that runs the same per-country payroll engines as net-salary-world.com. No key needed; 60 requests a minute per IP address. Figures are estimates for a standard employee, not tax advice; please link to the page a figure comes from.",
        "contact": {
            "name": "Pablo Bravo Villanueva",
            "email": "pablobravo44@gmail.com",
            "url": "https://net-salary-world.com/contact/"
        },
        "license": {
            "name": "Free with attribution",
            "url": "https://net-salary-world.com/terms/"
        }
    },
    "servers": [
        {
            "url": "https://net-salary-world.com"
        }
    ],
    "tags": [
        {
            "name": "Net salary",
            "description": "Gross to net for employees",
            "externalDocs": {
                "url": "https://net-salary-world.com/api/"
            }
        }
    ],
    "externalDocs": {
        "description": "API documentation",
        "url": "https://net-salary-world.com/api/"
    },
    "paths": {
        "/api/v1/net": {
            "get": {
                "operationId": "getNetSalary",
                "tags": [
                    "Net salary"
                ],
                "summary": "Net salary for a gross salary",
                "description": "Every tax and contribution line in annual amounts, net per year, month and week, how the year is paid, the tax year and the methodology page with the sources.",
                "parameters": [
                    {
                        "name": "cc",
                        "in": "query",
                        "required": true,
                        "description": "Country code.",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "gb",
                                "de",
                                "nl",
                                "ca",
                                "au"
                            ]
                        },
                        "example": "de"
                    },
                    {
                        "name": "gross",
                        "in": "query",
                        "required": true,
                        "description": "Gross salary in the country's currency (GBP, EUR, CAD, AUD): per year unless `period` is set. A comma as decimal separator is accepted.",
                        "schema": {
                            "type": "number",
                            "exclusiveMinimum": 0,
                            "maximum": 100000000
                        },
                        "example": 3000
                    },
                    {
                        "name": "period",
                        "in": "query",
                        "required": false,
                        "description": "Period the gross amount refers to.",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "year",
                                "month",
                                "fortnight",
                                "biweekly",
                                "week",
                                "hour"
                            ],
                            "default": "year"
                        }
                    },
                    {
                        "name": "region",
                        "in": "query",
                        "required": false,
                        "description": "Region where it matters (gb: ENG, SCT, WLS, NIR; de: NW, BY, BW, NI, HE, SN, RP, BE, SH, BB, ST, TH, HH, MV, SL, HB; ca: ON, QC, BC, AB, MB). Defaults to the country's default region. Aliases: `province`, `land`, `state`.",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "ENG",
                                "SCT",
                                "WLS",
                                "NIR",
                                "NW",
                                "BY",
                                "BW",
                                "NI",
                                "HE",
                                "SN",
                                "RP",
                                "BE",
                                "SH",
                                "BB",
                                "ST",
                                "TH",
                                "HH",
                                "MV",
                                "SL",
                                "HB",
                                "ON",
                                "QC",
                                "BC",
                                "AB",
                                "MB"
                            ]
                        }
                    },
                    {
                        "name": "year",
                        "in": "query",
                        "required": false,
                        "description": "Tax year (the year it starts in). Defaults to the year in force today. Available: gb: 2026; de: 2026; nl: 2026; ca: 2026; au: 2026.",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "student_loan",
                        "in": "query",
                        "required": false,
                        "description": "gb: Student loan. Invalid values fall back to the default.",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "none",
                                "plan1",
                                "plan2",
                                "plan4",
                                "plan5"
                            ],
                            "default": "none"
                        }
                    },
                    {
                        "name": "postgrad_loan",
                        "in": "query",
                        "required": false,
                        "description": "gb: Postgraduate loan. Invalid values fall back to the default.",
                        "schema": {
                            "type": "boolean",
                            "default": false
                        }
                    },
                    {
                        "name": "pension",
                        "in": "query",
                        "required": false,
                        "description": "gb: Pension contribution (% of salary). Auto-enrolment minimum: 5 %; nl: Employee pension contribution (% of gross). Found in your employment terms or on your payslip. Invalid values fall back to the default.",
                        "schema": {
                            "type": "number",
                            "minimum": 0,
                            "maximum": 60,
                            "default": 0
                        }
                    },
                    {
                        "name": "pension_method",
                        "in": "query",
                        "required": false,
                        "description": "gb: How the pension is paid. Invalid values fall back to the default.",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "net_pay",
                                "relief_at_source",
                                "salary_sacrifice"
                            ],
                            "default": "net_pay"
                        }
                    },
                    {
                        "name": "tax_class",
                        "in": "query",
                        "required": false,
                        "description": "de: Tax class (Steuerklasse). Invalid values fall back to the default. Alias: `class`.",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "1",
                                "2",
                                "3",
                                "4",
                                "5",
                                "6"
                            ],
                            "default": "1"
                        }
                    },
                    {
                        "name": "church",
                        "in": "query",
                        "required": false,
                        "description": "de: Church tax. 8 % of income tax in Bavaria and Baden-Württemberg, 9 % elsewhere. Only for registered church members. Invalid values fall back to the default.",
                        "schema": {
                            "type": "boolean",
                            "default": false
                        }
                    },
                    {
                        "name": "children",
                        "in": "query",
                        "required": false,
                        "description": "de: Children. Lowers solidarity surcharge and church tax through the child allowance, and the care insurance rate. Invalid values fall back to the default.",
                        "schema": {
                            "type": "integer",
                            "minimum": 0,
                            "maximum": 6,
                            "default": 0
                        }
                    },
                    {
                        "name": "under_23",
                        "in": "query",
                        "required": false,
                        "description": "de: Younger than 23. No childless surcharge on care insurance. Invalid values fall back to the default.",
                        "schema": {
                            "type": "boolean",
                            "default": false
                        }
                    },
                    {
                        "name": "health",
                        "in": "query",
                        "required": false,
                        "description": "de: Health insurance. Invalid values fall back to the default.",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "gkv",
                                "pkv"
                            ],
                            "default": "gkv"
                        }
                    },
                    {
                        "name": "zusatzbeitrag",
                        "in": "query",
                        "required": false,
                        "description": "de: Health fund add-on rate (%). 2026 average: 2.9 %. Invalid values fall back to the default.",
                        "schema": {
                            "type": "number",
                            "minimum": 0,
                            "maximum": 6,
                            "default": 2.9
                        }
                    },
                    {
                        "name": "pkv_premium",
                        "in": "query",
                        "required": false,
                        "description": "de: Private premium per month (health and care). Only with private insurance. Invalid values fall back to the default.",
                        "schema": {
                            "type": "number",
                            "minimum": 0,
                            "maximum": 3000,
                            "default": 0
                        }
                    },
                    {
                        "name": "holiday_pay",
                        "in": "query",
                        "required": false,
                        "description": "nl: Holiday pay (8 %) on top of the monthly salary. Invalid values fall back to the default.",
                        "schema": {
                            "type": "boolean",
                            "default": true
                        }
                    },
                    {
                        "name": "thirteenth_month",
                        "in": "query",
                        "required": false,
                        "description": "nl: 13th month. Invalid values fall back to the default.",
                        "schema": {
                            "type": "boolean",
                            "default": false
                        }
                    },
                    {
                        "name": "tax_credit",
                        "in": "query",
                        "required": false,
                        "description": "nl: Apply the payroll tax credit. Switch on with one employer only; usually off for a second job. Invalid values fall back to the default.",
                        "schema": {
                            "type": "boolean",
                            "default": true
                        }
                    },
                    {
                        "name": "special_annual_wage",
                        "in": "query",
                        "required": false,
                        "description": "nl: Special-pay reference annual wage. Use your employer's annual wage for special payments (normally based on the previous year). 0 estimates it from this scenario's annual taxable pay; that can differ from payroll. Invalid values fall back to the default.",
                        "schema": {
                            "type": "number",
                            "minimum": 0,
                            "maximum": 10000000,
                            "default": 0
                        }
                    },
                    {
                        "name": "rrsp",
                        "in": "query",
                        "required": false,
                        "description": "ca: RRSP or registered pension deduction ($ a year). Lowers income tax, not CPP or EI. Invalid values fall back to the default.",
                        "schema": {
                            "type": "number",
                            "minimum": 0,
                            "maximum": 40000,
                            "default": 0
                        }
                    },
                    {
                        "name": "super_included",
                        "in": "query",
                        "required": false,
                        "description": "au: The salary includes super (a package). Tick if your offer says \"including super\". Invalid values fall back to the default.",
                        "schema": {
                            "type": "boolean",
                            "default": false
                        }
                    },
                    {
                        "name": "help",
                        "in": "query",
                        "required": false,
                        "description": "au: HELP / HECS debt. Invalid values fall back to the default.",
                        "schema": {
                            "type": "boolean",
                            "default": false
                        }
                    },
                    {
                        "name": "private_cover",
                        "in": "query",
                        "required": false,
                        "description": "au: Private hospital cover. Without it, the Medicare levy surcharge applies above $105,000. Invalid values fall back to the default.",
                        "schema": {
                            "type": "boolean",
                            "default": true
                        }
                    },
                    {
                        "name": "standard_deduction",
                        "in": "query",
                        "required": false,
                        "description": "au: Claim the $1,000 standard deduction. Eligible resident employment income only; no overlapping work deductions. Enacted for 2026-27, capped at $1,000 or assessable labour income if lower. This affects annual assessment, not automatic PAYG withholding. Invalid values fall back to the default.",
                        "schema": {
                            "type": "boolean",
                            "default": false
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The calculation.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/NetSalary"
                                },
                                "example": {
                                    "country": "de",
                                    "tax_year": "2026",
                                    "currency": "EUR",
                                    "input": {
                                        "gross": 3000,
                                        "period": "month",
                                        "gross_annual": 36000,
                                        "region": "NW",
                                        "options": {
                                            "tax_class": "1",
                                            "church": false,
                                            "children": 0,
                                            "under_23": false,
                                            "health": "gkv",
                                            "zusatzbeitrag": 2.9,
                                            "pkv_premium": 0
                                        }
                                    },
                                    "result": {
                                        "gross": 36000,
                                        "net": 24653.04,
                                        "deductions": 11346.96,
                                        "effective_rate": 0.3152,
                                        "lines": [
                                            {
                                                "key": "income_tax",
                                                "amount": 3516.96,
                                                "kind": "tax",
                                                "rate": null
                                            },
                                            {
                                                "key": "solidarity_surcharge",
                                                "amount": 0,
                                                "kind": "tax",
                                                "rate": 0.055
                                            },
                                            {
                                                "key": "health_insurance",
                                                "amount": 3150,
                                                "kind": "contribution",
                                                "rate": 0.0875
                                            },
                                            {
                                                "key": "care_insurance",
                                                "amount": 864,
                                                "kind": "contribution",
                                                "rate": 0.024
                                            },
                                            {
                                                "key": "pension_insurance",
                                                "amount": 3348,
                                                "kind": "contribution",
                                                "rate": 0.093
                                            },
                                            {
                                                "key": "unemployment_insurance",
                                                "amount": 468,
                                                "kind": "contribution",
                                                "rate": 0.013
                                            }
                                        ],
                                        "payments": [
                                            {
                                                "key": "regular",
                                                "count": 12,
                                                "gross": 3000,
                                                "net": 2054.42
                                            }
                                        ]
                                    },
                                    "net": {
                                        "year": 24653.04,
                                        "month": 2054.42,
                                        "week": 474.1
                                    },
                                    "unverified_rules": [],
                                    "sources": "https://net-salary-world.com/de-de/methodik/",
                                    "disclaimer": "Estimate for a standard employee under the stated options; not tax advice."
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "`invalid_gross` (gross missing, not a number, zero or above 100000000) or `invalid_period`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "`unknown_country` (lists `countries`), `unknown_year` (lists `years`) or `unknown_region` (lists `regions`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "`rate_limited`: more than 60 requests in a minute from one IP address.",
                        "headers": {
                            "Retry-After": {
                                "description": "Seconds until the next minute starts.",
                                "schema": {
                                    "type": "integer"
                                }
                            }
                        },
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "NetSalary": {
                "type": "object",
                "required": [
                    "country",
                    "tax_year",
                    "currency",
                    "input",
                    "result",
                    "net"
                ],
                "properties": {
                    "country": {
                        "type": "string",
                        "enum": [
                            "gb",
                            "de",
                            "nl",
                            "ca",
                            "au"
                        ]
                    },
                    "tax_year": {
                        "type": "string",
                        "description": "Tax year label, e.g. 2026, 2026/27 or 2026–27."
                    },
                    "currency": {
                        "type": "string",
                        "description": "ISO 4217 code."
                    },
                    "input": {
                        "type": "object",
                        "properties": {
                            "gross": {
                                "type": "number"
                            },
                            "period": {
                                "type": "string",
                                "enum": [
                                    "year",
                                    "month",
                                    "fortnight",
                                    "biweekly",
                                    "week",
                                    "hour"
                                ]
                            },
                            "gross_annual": {
                                "type": "number"
                            },
                            "region": {
                                "type": [
                                    "string",
                                    "null"
                                ]
                            },
                            "options": {
                                "type": "object",
                                "description": "Every option of the country after validation: the assumptions used."
                            }
                        }
                    },
                    "result": {
                        "type": "object",
                        "properties": {
                            "gross": {
                                "type": "number",
                                "description": "Annual gross."
                            },
                            "net": {
                                "type": "number",
                                "description": "Annual net (take-home) pay."
                            },
                            "deductions": {
                                "type": "number",
                                "description": "Annual tax and contributions deducted."
                            },
                            "effective_rate": {
                                "type": "number",
                                "description": "deductions / gross."
                            },
                            "lines": {
                                "type": "array",
                                "items": {
                                    "$ref": "#/components/schemas/Line"
                                }
                            },
                            "payments": {
                                "type": "array",
                                "items": {
                                    "$ref": "#/components/schemas/Payment"
                                }
                            }
                        }
                    },
                    "net": {
                        "type": "object",
                        "properties": {
                            "year": {
                                "type": "number"
                            },
                            "month": {
                                "type": "number"
                            },
                            "week": {
                                "type": "number"
                            }
                        }
                    },
                    "unverified_rules": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "description": "Rule values used by this result that are not yet confirmed with an official source."
                    },
                    "sources": {
                        "type": "string",
                        "format": "uri",
                        "description": "Methodology page listing every source."
                    },
                    "disclaimer": {
                        "type": "string"
                    }
                }
            },
            "Line": {
                "type": "object",
                "properties": {
                    "key": {
                        "type": "string",
                        "description": "e.g. income_tax, national_insurance, health_insurance."
                    },
                    "amount": {
                        "type": "number",
                        "description": "Annual amount."
                    },
                    "kind": {
                        "type": "string",
                        "enum": [
                            "tax",
                            "contribution",
                            "deduction",
                            "credit",
                            "info",
                            "employer"
                        ],
                        "description": "tax, contribution and deduction lines are subtracted; credit is already netted into its tax; info and employer lines are shown only."
                    },
                    "rate": {
                        "type": [
                            "number",
                            "null"
                        ]
                    }
                }
            },
            "Payment": {
                "type": "object",
                "properties": {
                    "key": {
                        "type": "string",
                        "description": "regular, holiday_pay, extra, …"
                    },
                    "count": {
                        "type": "number",
                        "description": "Payments of this kind per year."
                    },
                    "gross": {
                        "type": "number"
                    },
                    "net": {
                        "type": "number"
                    }
                }
            },
            "Error": {
                "type": "object",
                "required": [
                    "error"
                ],
                "properties": {
                    "error": {
                        "type": "string",
                        "enum": [
                            "unknown_country",
                            "invalid_gross",
                            "invalid_period",
                            "unknown_year",
                            "unknown_region",
                            "rate_limited"
                        ]
                    },
                    "hint": {
                        "type": "string"
                    },
                    "countries": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "years": {
                        "type": "array",
                        "items": {
                            "type": "integer"
                        }
                    },
                    "regions": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "limit_per_minute": {
                        "type": "integer"
                    }
                }
            }
        }
    }
}