{
  "openapi": "3.1.0",
  "info": {
    "title": "IsMyPayRight API",
    "version": "1.0.0",
    "description": "Programmatic access to UK PAYE tax calculations. Calculate take-home pay, check payslips, reverse-calculate gross from net, and more - powered by the same engine as ismypayright.co.uk.",
    "contact": {
      "name": "IsMyPayRight",
      "url": "https://www.ismypayright.co.uk/api/docs"
    }
  },
  "servers": [
    {
      "url": "https://www.ismypayright.co.uk",
      "description": "Production"
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key from Unkey. Optional - unauthenticated requests use the free tier (10/hour)."
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "details": {}
            },
            "required": [
              "code",
              "message"
            ]
          }
        },
        "required": [
          "error"
        ]
      }
    },
    "parameters": {}
  },
  "paths": {
    "/api/v1/calculate": {
      "post": {
        "summary": "Calculate take-home pay",
        "description": "Full UK PAYE calculation including income tax, NI, student loans, pension, and salary sacrifice.",
        "operationId": "calculateSalary",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "taxYear": {
                    "type": "string",
                    "enum": [
                      "2024-25",
                      "2025-26",
                      "2026-27"
                    ]
                  },
                  "region": {
                    "type": "string",
                    "enum": [
                      "england",
                      "wales",
                      "scotland",
                      "northern-ireland"
                    ]
                  },
                  "salary": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 1000000000
                  },
                  "frequency": {
                    "type": "string",
                    "enum": [
                      "year",
                      "month",
                      "fourWeeks",
                      "twoWeeks",
                      "week",
                      "day",
                      "hour"
                    ]
                  },
                  "taxCode": {
                    "type": "string",
                    "maxLength": 20
                  },
                  "studentLoans": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "plan1",
                        "plan2",
                        "plan4",
                        "plan5",
                        "postgraduate"
                      ]
                    },
                    "maxItems": 10
                  },
                  "pension": {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "percent",
                          "fixed"
                        ]
                      },
                      "value": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 1000000000
                      },
                      "relief": {
                        "type": "string",
                        "enum": [
                          "net",
                          "gross",
                          "net_pay"
                        ]
                      }
                    },
                    "required": [
                      "type",
                      "value",
                      "relief"
                    ],
                    "additionalProperties": false
                  },
                  "childrenCount": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 100
                  },
                  "married": {
                    "type": "boolean"
                  },
                  "partnerIncome": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 1000000000
                  },
                  "blind": {
                    "type": "boolean"
                  },
                  "noNI": {
                    "type": "boolean"
                  },
                  "bonus": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 1000000000
                  },
                  "additionalAllowances": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 1000000000
                  },
                  "hoursPerWeek": {
                    "type": "number",
                    "exclusiveMinimum": 0,
                    "maximum": 168
                  },
                  "salarySacrifice": {
                    "type": "array",
                    "items": {
                      "oneOf": [
                        {
                          "type": "object",
                          "properties": {
                            "scheme": {
                              "type": "string",
                              "enum": [
                                "cycle_to_work"
                              ]
                            },
                            "amount": {
                              "type": "number",
                              "minimum": 0,
                              "maximum": 1000000000
                            }
                          },
                          "required": [
                            "scheme",
                            "amount"
                          ],
                          "additionalProperties": false
                        },
                        {
                          "type": "object",
                          "properties": {
                            "scheme": {
                              "type": "string",
                              "enum": [
                                "holiday_buy"
                              ]
                            },
                            "amount": {
                              "type": "number",
                              "minimum": 0,
                              "maximum": 1000000000
                            },
                            "days": {
                              "type": "number",
                              "minimum": 0
                            }
                          },
                          "required": [
                            "scheme",
                            "amount"
                          ],
                          "additionalProperties": false
                        },
                        {
                          "type": "object",
                          "properties": {
                            "scheme": {
                              "type": "string",
                              "enum": [
                                "ev_car"
                              ]
                            },
                            "amount": {
                              "type": "number",
                              "minimum": 0,
                              "maximum": 1000000000
                            },
                            "monthlyAmount": {
                              "type": "number",
                              "minimum": 0
                            },
                            "leaseMonths": {
                              "type": "number",
                              "minimum": 0
                            },
                            "p11dValue": {
                              "type": "number",
                              "minimum": 0,
                              "maximum": 1000000000
                            }
                          },
                          "required": [
                            "scheme",
                            "amount"
                          ],
                          "additionalProperties": false
                        },
                        {
                          "type": "object",
                          "properties": {
                            "scheme": {
                              "type": "string",
                              "enum": [
                                "pension_increase"
                              ]
                            },
                            "amount": {
                              "type": "number",
                              "minimum": 0,
                              "maximum": 1000000000
                            }
                          },
                          "required": [
                            "scheme",
                            "amount"
                          ],
                          "additionalProperties": false
                        }
                      ]
                    }
                  }
                },
                "required": [
                  "taxYear",
                  "region",
                  "salary",
                  "frequency"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful calculation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "inputs": {
                          "type": "object",
                          "properties": {
                            "taxYear": {
                              "type": "string"
                            },
                            "region": {
                              "type": "string",
                              "enum": [
                                "england",
                                "wales",
                                "scotland",
                                "northern-ireland"
                              ]
                            },
                            "salary": {
                              "type": "number"
                            },
                            "frequency": {
                              "type": "string",
                              "enum": [
                                "year",
                                "month",
                                "fourWeeks",
                                "twoWeeks",
                                "week",
                                "day",
                                "hour"
                              ]
                            },
                            "taxCode": {
                              "type": "string"
                            },
                            "studentLoans": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              }
                            },
                            "pension": {
                              "type": "object",
                              "properties": {
                                "type": {
                                  "type": "string",
                                  "enum": [
                                    "percent",
                                    "fixed"
                                  ]
                                },
                                "value": {
                                  "type": "number"
                                },
                                "relief": {
                                  "type": "string",
                                  "enum": [
                                    "net",
                                    "gross",
                                    "net_pay"
                                  ]
                                }
                              },
                              "required": [
                                "type",
                                "value",
                                "relief"
                              ]
                            },
                            "personalPension": {
                              "type": "object",
                              "properties": {
                                "type": {
                                  "type": "string",
                                  "enum": [
                                    "percent",
                                    "fixed"
                                  ]
                                },
                                "value": {
                                  "type": "number"
                                }
                              },
                              "required": [
                                "type",
                                "value"
                              ]
                            },
                            "childrenCount": {
                              "type": "number"
                            },
                            "married": {
                              "type": "boolean"
                            },
                            "partnerIncome": {
                              "type": "number"
                            },
                            "blind": {
                              "type": "boolean"
                            },
                            "noNI": {
                              "type": "boolean"
                            },
                            "age": {
                              "type": "string",
                              "enum": [
                                "under65",
                                "65to74",
                                "over75"
                              ]
                            },
                            "overtime": {
                              "type": "object",
                              "properties": {
                                "hours": {
                                  "type": "number"
                                },
                                "rate": {
                                  "type": "number"
                                }
                              },
                              "required": [
                                "hours",
                                "rate"
                              ]
                            },
                            "bonus": {
                              "type": "number"
                            },
                            "additionalAllowances": {
                              "type": "number"
                            },
                            "hoursPerWeek": {
                              "type": "number"
                            },
                            "salarySacrifice": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "scheme": {
                                    "type": "string",
                                    "enum": [
                                      "cycle_to_work",
                                      "holiday_buy",
                                      "ev_car",
                                      "pension_increase"
                                    ]
                                  },
                                  "amount": {
                                    "type": "number"
                                  },
                                  "days": {
                                    "type": "number"
                                  },
                                  "monthlyAmount": {
                                    "type": "number"
                                  },
                                  "leaseMonths": {
                                    "type": "number"
                                  },
                                  "p11dValue": {
                                    "type": "number"
                                  }
                                },
                                "required": [
                                  "scheme",
                                  "amount"
                                ]
                              }
                            }
                          },
                          "required": [
                            "taxYear",
                            "region",
                            "salary",
                            "frequency"
                          ]
                        },
                        "grossAnnual": {
                          "type": "number"
                        },
                        "personalAllowance": {
                          "type": "number"
                        },
                        "taxableIncome": {
                          "type": "number"
                        },
                        "incomeTax": {
                          "type": "object",
                          "properties": {
                            "taxableIncome": {
                              "type": "number"
                            },
                            "personalAllowance": {
                              "type": "number"
                            },
                            "bands": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "name": {
                                    "type": "string"
                                  },
                                  "rate": {
                                    "type": "number"
                                  },
                                  "taxable": {
                                    "type": "number"
                                  },
                                  "tax": {
                                    "type": "number"
                                  }
                                },
                                "required": [
                                  "name",
                                  "rate",
                                  "taxable",
                                  "tax"
                                ]
                              }
                            },
                            "totalTax": {
                              "type": "number"
                            },
                            "effectiveRate": {
                              "type": "number"
                            },
                            "marginalRate": {
                              "type": "number"
                            }
                          },
                          "required": [
                            "taxableIncome",
                            "personalAllowance",
                            "bands",
                            "totalTax",
                            "effectiveRate",
                            "marginalRate"
                          ]
                        },
                        "nationalInsurance": {
                          "type": "object",
                          "properties": {
                            "employee": {
                              "type": "object",
                              "properties": {
                                "earnings": {
                                  "type": "number"
                                },
                                "mainContribution": {
                                  "type": "number"
                                },
                                "upperContribution": {
                                  "type": "number"
                                },
                                "totalContribution": {
                                  "type": "number"
                                },
                                "effectiveRate": {
                                  "type": "number"
                                }
                              },
                              "required": [
                                "earnings",
                                "mainContribution",
                                "upperContribution",
                                "totalContribution",
                                "effectiveRate"
                              ]
                            },
                            "employer": {
                              "type": "object",
                              "properties": {
                                "earnings": {
                                  "type": "number"
                                },
                                "contribution": {
                                  "type": "number"
                                },
                                "effectiveRate": {
                                  "type": "number"
                                }
                              },
                              "required": [
                                "earnings",
                                "contribution",
                                "effectiveRate"
                              ]
                            }
                          },
                          "required": [
                            "employee",
                            "employer"
                          ]
                        },
                        "studentLoans": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "plan": {
                                "type": "string"
                              },
                              "threshold": {
                                "type": "number"
                              },
                              "rate": {
                                "type": "number"
                              },
                              "repayment": {
                                "type": "number"
                              }
                            },
                            "required": [
                              "plan",
                              "threshold",
                              "rate",
                              "repayment"
                            ]
                          }
                        },
                        "pension": {
                          "type": "object",
                          "properties": {
                            "employeeContribution": {
                              "type": "number"
                            },
                            "employerContribution": {
                              "type": "number"
                            },
                            "taxRelief": {
                              "type": "number"
                            },
                            "sacrificeAmount": {
                              "type": "number"
                            }
                          },
                          "required": [
                            "employeeContribution",
                            "employerContribution",
                            "taxRelief",
                            "sacrificeAmount"
                          ]
                        },
                        "salarySacrifice": {
                          "type": "object",
                          "properties": {
                            "schemes": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "scheme": {
                                    "type": "string",
                                    "enum": [
                                      "cycle_to_work",
                                      "holiday_buy",
                                      "ev_car",
                                      "pension_increase"
                                    ]
                                  },
                                  "amount": {
                                    "type": "number"
                                  },
                                  "displayName": {
                                    "type": "string"
                                  },
                                  "days": {
                                    "type": "number"
                                  },
                                  "monthlyAmount": {
                                    "type": "number"
                                  },
                                  "leaseMonths": {
                                    "type": "number"
                                  },
                                  "p11dValue": {
                                    "type": "number"
                                  }
                                },
                                "required": [
                                  "scheme",
                                  "amount",
                                  "displayName"
                                ]
                              }
                            },
                            "totalSacrifice": {
                              "type": "number"
                            },
                            "adjustedGross": {
                              "type": "number"
                            },
                            "taxSaving": {
                              "type": "number"
                            },
                            "niSaving": {
                              "type": "number"
                            },
                            "benefitInKindTax": {
                              "type": "number"
                            },
                            "effectiveSaving": {
                              "type": "number"
                            },
                            "netCostToEmployee": {
                              "type": "number"
                            },
                            "takeHomeChange": {
                              "type": "number"
                            },
                            "warnings": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              }
                            }
                          },
                          "required": [
                            "schemes",
                            "totalSacrifice",
                            "adjustedGross",
                            "taxSaving",
                            "niSaving",
                            "benefitInKindTax",
                            "effectiveSaving",
                            "netCostToEmployee",
                            "takeHomeChange",
                            "warnings"
                          ]
                        },
                        "childBenefit": {
                          "type": "object",
                          "properties": {
                            "weeklyBenefit": {
                              "type": "number"
                            },
                            "annualBenefit": {
                              "type": "number"
                            },
                            "hiChargeRate": {
                              "type": "number"
                            },
                            "hiChargeAmount": {
                              "type": "number"
                            },
                            "netBenefit": {
                              "type": "number"
                            }
                          },
                          "required": [
                            "weeklyBenefit",
                            "annualBenefit",
                            "hiChargeRate",
                            "hiChargeAmount",
                            "netBenefit"
                          ]
                        },
                        "marriageAllowance": {
                          "type": "object",
                          "properties": {
                            "transferred": {
                              "type": "number"
                            },
                            "taxSaving": {
                              "type": "number"
                            }
                          },
                          "required": [
                            "transferred",
                            "taxSaving"
                          ]
                        },
                        "totalDeductions": {
                          "type": "number"
                        },
                        "netAnnual": {
                          "type": "number"
                        },
                        "breakdown": {
                          "type": "object",
                          "properties": {
                            "yearly": {
                              "type": "object",
                              "properties": {
                                "gross": {
                                  "type": "number"
                                },
                                "salarySacrifice": {
                                  "type": "number"
                                },
                                "taxablePay": {
                                  "type": "number"
                                },
                                "incomeTax": {
                                  "type": "number"
                                },
                                "benefitInKindTax": {
                                  "type": "number"
                                },
                                "nationalInsurance": {
                                  "type": "number"
                                },
                                "studentLoan": {
                                  "type": "number"
                                },
                                "pension": {
                                  "type": "number"
                                },
                                "totalDeductions": {
                                  "type": "number"
                                },
                                "net": {
                                  "type": "number"
                                }
                              },
                              "required": [
                                "gross",
                                "salarySacrifice",
                                "taxablePay",
                                "incomeTax",
                                "benefitInKindTax",
                                "nationalInsurance",
                                "studentLoan",
                                "pension",
                                "totalDeductions",
                                "net"
                              ]
                            },
                            "monthly": {
                              "type": "object",
                              "properties": {
                                "gross": {
                                  "type": "number"
                                },
                                "salarySacrifice": {
                                  "type": "number"
                                },
                                "taxablePay": {
                                  "type": "number"
                                },
                                "incomeTax": {
                                  "type": "number"
                                },
                                "benefitInKindTax": {
                                  "type": "number"
                                },
                                "nationalInsurance": {
                                  "type": "number"
                                },
                                "studentLoan": {
                                  "type": "number"
                                },
                                "pension": {
                                  "type": "number"
                                },
                                "totalDeductions": {
                                  "type": "number"
                                },
                                "net": {
                                  "type": "number"
                                }
                              },
                              "required": [
                                "gross",
                                "salarySacrifice",
                                "taxablePay",
                                "incomeTax",
                                "benefitInKindTax",
                                "nationalInsurance",
                                "studentLoan",
                                "pension",
                                "totalDeductions",
                                "net"
                              ]
                            },
                            "fourWeekly": {
                              "type": "object",
                              "properties": {
                                "gross": {
                                  "type": "number"
                                },
                                "salarySacrifice": {
                                  "type": "number"
                                },
                                "taxablePay": {
                                  "type": "number"
                                },
                                "incomeTax": {
                                  "type": "number"
                                },
                                "benefitInKindTax": {
                                  "type": "number"
                                },
                                "nationalInsurance": {
                                  "type": "number"
                                },
                                "studentLoan": {
                                  "type": "number"
                                },
                                "pension": {
                                  "type": "number"
                                },
                                "totalDeductions": {
                                  "type": "number"
                                },
                                "net": {
                                  "type": "number"
                                }
                              },
                              "required": [
                                "gross",
                                "salarySacrifice",
                                "taxablePay",
                                "incomeTax",
                                "benefitInKindTax",
                                "nationalInsurance",
                                "studentLoan",
                                "pension",
                                "totalDeductions",
                                "net"
                              ]
                            },
                            "twoWeekly": {
                              "type": "object",
                              "properties": {
                                "gross": {
                                  "type": "number"
                                },
                                "salarySacrifice": {
                                  "type": "number"
                                },
                                "taxablePay": {
                                  "type": "number"
                                },
                                "incomeTax": {
                                  "type": "number"
                                },
                                "benefitInKindTax": {
                                  "type": "number"
                                },
                                "nationalInsurance": {
                                  "type": "number"
                                },
                                "studentLoan": {
                                  "type": "number"
                                },
                                "pension": {
                                  "type": "number"
                                },
                                "totalDeductions": {
                                  "type": "number"
                                },
                                "net": {
                                  "type": "number"
                                }
                              },
                              "required": [
                                "gross",
                                "salarySacrifice",
                                "taxablePay",
                                "incomeTax",
                                "benefitInKindTax",
                                "nationalInsurance",
                                "studentLoan",
                                "pension",
                                "totalDeductions",
                                "net"
                              ]
                            },
                            "weekly": {
                              "type": "object",
                              "properties": {
                                "gross": {
                                  "type": "number"
                                },
                                "salarySacrifice": {
                                  "type": "number"
                                },
                                "taxablePay": {
                                  "type": "number"
                                },
                                "incomeTax": {
                                  "type": "number"
                                },
                                "benefitInKindTax": {
                                  "type": "number"
                                },
                                "nationalInsurance": {
                                  "type": "number"
                                },
                                "studentLoan": {
                                  "type": "number"
                                },
                                "pension": {
                                  "type": "number"
                                },
                                "totalDeductions": {
                                  "type": "number"
                                },
                                "net": {
                                  "type": "number"
                                }
                              },
                              "required": [
                                "gross",
                                "salarySacrifice",
                                "taxablePay",
                                "incomeTax",
                                "benefitInKindTax",
                                "nationalInsurance",
                                "studentLoan",
                                "pension",
                                "totalDeductions",
                                "net"
                              ]
                            },
                            "daily": {
                              "type": "object",
                              "properties": {
                                "gross": {
                                  "type": "number"
                                },
                                "salarySacrifice": {
                                  "type": "number"
                                },
                                "taxablePay": {
                                  "type": "number"
                                },
                                "incomeTax": {
                                  "type": "number"
                                },
                                "benefitInKindTax": {
                                  "type": "number"
                                },
                                "nationalInsurance": {
                                  "type": "number"
                                },
                                "studentLoan": {
                                  "type": "number"
                                },
                                "pension": {
                                  "type": "number"
                                },
                                "totalDeductions": {
                                  "type": "number"
                                },
                                "net": {
                                  "type": "number"
                                }
                              },
                              "required": [
                                "gross",
                                "salarySacrifice",
                                "taxablePay",
                                "incomeTax",
                                "benefitInKindTax",
                                "nationalInsurance",
                                "studentLoan",
                                "pension",
                                "totalDeductions",
                                "net"
                              ]
                            },
                            "hourly": {
                              "type": "object",
                              "properties": {
                                "gross": {
                                  "type": "number"
                                },
                                "salarySacrifice": {
                                  "type": "number"
                                },
                                "taxablePay": {
                                  "type": "number"
                                },
                                "incomeTax": {
                                  "type": "number"
                                },
                                "benefitInKindTax": {
                                  "type": "number"
                                },
                                "nationalInsurance": {
                                  "type": "number"
                                },
                                "studentLoan": {
                                  "type": "number"
                                },
                                "pension": {
                                  "type": "number"
                                },
                                "totalDeductions": {
                                  "type": "number"
                                },
                                "net": {
                                  "type": "number"
                                }
                              },
                              "required": [
                                "gross",
                                "salarySacrifice",
                                "taxablePay",
                                "incomeTax",
                                "benefitInKindTax",
                                "nationalInsurance",
                                "studentLoan",
                                "pension",
                                "totalDeductions",
                                "net"
                              ]
                            }
                          },
                          "required": [
                            "yearly",
                            "monthly",
                            "fourWeekly",
                            "twoWeekly",
                            "weekly",
                            "daily",
                            "hourly"
                          ]
                        },
                        "effectiveTaxRate": {
                          "type": "number"
                        },
                        "marginalTaxRate": {
                          "type": "number"
                        },
                        "previousYear": {
                          "type": "object",
                          "properties": {
                            "netAnnual": {
                              "type": "number"
                            },
                            "difference": {
                              "type": "number"
                            },
                            "differenceMonthly": {
                              "type": "number"
                            }
                          },
                          "required": [
                            "netAnnual",
                            "difference",
                            "differenceMonthly"
                          ]
                        }
                      },
                      "required": [
                        "inputs",
                        "grossAnnual",
                        "personalAllowance",
                        "taxableIncome",
                        "incomeTax",
                        "nationalInsurance",
                        "studentLoans",
                        "pension",
                        "salarySacrifice",
                        "totalDeductions",
                        "netAnnual",
                        "breakdown",
                        "effectiveTaxRate",
                        "marginalTaxRate"
                      ]
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "version": {
                          "type": "string"
                        },
                        "taxYear": {
                          "type": "string"
                        },
                        "calculatedAt": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "version",
                        "taxYear",
                        "calculatedAt"
                      ]
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Validation error (VALIDATION_ERROR) or malformed JSON (INVALID_JSON)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "API key is invalid, disabled, or expired (INVALID_KEY)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded (RATE_LIMITED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Auth or rate limiting not configured (AUTH_UNAVAILABLE, SERVICE_UNAVAILABLE)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/check": {
      "post": {
        "summary": "Check a payslip",
        "description": "Validates payslip figures against expected HMRC calculations and identifies discrepancies.",
        "operationId": "checkPayslip",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "taxYear": {
                    "type": "string",
                    "enum": [
                      "2024-25",
                      "2025-26",
                      "2026-27"
                    ]
                  },
                  "grossMonthly": {
                    "type": "number",
                    "exclusiveMinimum": 0
                  },
                  "payFrequency": {
                    "type": "string",
                    "enum": [
                      "month",
                      "fourWeeks",
                      "twoWeeks",
                      "week"
                    ]
                  },
                  "payeTax": {
                    "type": "number",
                    "minimum": 0
                  },
                  "nationalInsurance": {
                    "type": "number",
                    "minimum": 0
                  },
                  "pension": {
                    "type": "number",
                    "minimum": 0
                  },
                  "pensionMethod": {
                    "type": "string",
                    "enum": [
                      "relief_at_source",
                      "net_pay",
                      "unknown"
                    ]
                  },
                  "studentLoan": {
                    "type": "number",
                    "minimum": 0
                  },
                  "netPay": {
                    "type": "number",
                    "exclusiveMinimum": 0
                  },
                  "taxCode": {
                    "type": "string",
                    "minLength": 1
                  },
                  "region": {
                    "type": "string",
                    "enum": [
                      "england",
                      "wales",
                      "scotland",
                      "northern-ireland"
                    ]
                  },
                  "studentLoanPlan": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "plan1",
                        "plan2",
                        "plan4",
                        "plan5",
                        "postgraduate"
                      ]
                    }
                  },
                  "complexity": {
                    "type": "object",
                    "properties": {
                      "salarySacrifice": {
                        "type": "object",
                        "properties": {
                          "pension": {
                            "type": "number",
                            "minimum": 0
                          },
                          "electricCar": {
                            "type": "number",
                            "minimum": 0
                          },
                          "other": {
                            "type": "number",
                            "minimum": 0
                          }
                        },
                        "additionalProperties": false
                      },
                      "taxableBenefits": {
                        "type": "object",
                        "properties": {
                          "electricCar": {
                            "type": "number",
                            "minimum": 0
                          },
                          "medical": {
                            "type": "number",
                            "minimum": 0
                          },
                          "other": {
                            "type": "number",
                            "minimum": 0
                          }
                        },
                        "additionalProperties": false
                      },
                      "otherDeductions": {
                        "type": "number",
                        "minimum": 0
                      }
                    },
                    "additionalProperties": false
                  }
                },
                "required": [
                  "grossMonthly",
                  "payeTax",
                  "nationalInsurance",
                  "netPay",
                  "taxCode",
                  "region"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful calculation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "overall": {
                          "type": "string",
                          "enum": [
                            "correct",
                            "minor_issues",
                            "issues_found"
                          ]
                        },
                        "items": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "field": {
                                "type": "string"
                              },
                              "status": {
                                "type": "string",
                                "enum": [
                                  "correct",
                                  "minor_difference",
                                  "overpaid",
                                  "underpaid"
                                ]
                              },
                              "payslipValue": {
                                "type": "number"
                              },
                              "expectedValue": {
                                "type": "number"
                              },
                              "difference": {
                                "type": "number"
                              },
                              "possibleReasons": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              },
                              "actions": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              }
                            },
                            "required": [
                              "field",
                              "status",
                              "payslipValue",
                              "expectedValue",
                              "difference",
                              "possibleReasons",
                              "actions"
                            ]
                          }
                        },
                        "reconciliation": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "key": {
                                "type": "string"
                              },
                              "label": {
                                "type": "string"
                              },
                              "amount": {
                                "type": "number"
                              },
                              "tone": {
                                "type": "string",
                                "enum": [
                                  "positive",
                                  "negative",
                                  "neutral",
                                  "result"
                                ]
                              },
                              "description": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "key",
                              "label",
                              "amount",
                              "tone"
                            ]
                          }
                        },
                        "integrityIssues": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "field": {
                                "type": "string",
                                "enum": [
                                  "net_pay_arithmetic",
                                  "deduction_exceeds_gross",
                                  "net_exceeds_gross"
                                ]
                              },
                              "message": {
                                "type": "string"
                              },
                              "details": {
                                "type": "string"
                              },
                              "expectedValue": {
                                "type": "number"
                              },
                              "actualValue": {
                                "type": "number"
                              }
                            },
                            "required": [
                              "field",
                              "message",
                              "details"
                            ]
                          }
                        },
                        "summary": {
                          "type": "object",
                          "properties": {
                            "usesComplexity": {
                              "type": "boolean"
                            },
                            "payFrequency": {
                              "type": "string"
                            },
                            "notes": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              }
                            },
                            "canShowSalaryPageLink": {
                              "type": "boolean"
                            },
                            "annualisedSalary": {
                              "type": "number"
                            }
                          },
                          "required": [
                            "usesComplexity",
                            "payFrequency",
                            "notes",
                            "canShowSalaryPageLink"
                          ]
                        },
                        "benefitTeaser": {
                          "type": [
                            "object",
                            "null"
                          ],
                          "properties": {
                            "monthlySaving": {
                              "type": "number"
                            },
                            "bestBenefit": {
                              "type": "string"
                            },
                            "description": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "monthlySaving",
                            "bestBenefit",
                            "description"
                          ]
                        }
                      },
                      "required": [
                        "overall",
                        "items",
                        "reconciliation",
                        "integrityIssues",
                        "summary",
                        "benefitTeaser"
                      ]
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "version": {
                          "type": "string"
                        },
                        "taxYear": {
                          "type": "string"
                        },
                        "calculatedAt": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "version",
                        "taxYear",
                        "calculatedAt"
                      ]
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Validation error (VALIDATION_ERROR) or malformed JSON (INVALID_JSON)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "API key is invalid, disabled, or expired (INVALID_KEY)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded (RATE_LIMITED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Auth or rate limiting not configured (AUTH_UNAVAILABLE, SERVICE_UNAVAILABLE)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/reverse": {
      "post": {
        "summary": "Reverse-calculate gross from net",
        "description": "Given a target net pay, calculates the gross salary required to achieve it. targetNet follows the frequency set in options.frequency.",
        "operationId": "reverseCalculate",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "targetNet": {
                    "type": "number",
                    "exclusiveMinimum": 0,
                    "maximum": 1000000000
                  },
                  "options": {
                    "type": "object",
                    "properties": {
                      "taxYear": {
                        "type": "string",
                        "enum": [
                          "2024-25",
                          "2025-26",
                          "2026-27"
                        ]
                      },
                      "region": {
                        "type": "string",
                        "enum": [
                          "england",
                          "wales",
                          "scotland",
                          "northern-ireland"
                        ]
                      },
                      "frequency": {
                        "type": "string",
                        "enum": [
                          "year",
                          "month",
                          "fourWeeks",
                          "twoWeeks",
                          "week",
                          "day",
                          "hour"
                        ]
                      },
                      "taxCode": {
                        "type": "string",
                        "maxLength": 20
                      },
                      "studentLoans": {
                        "type": "array",
                        "items": {
                          "type": "string",
                          "enum": [
                            "plan1",
                            "plan2",
                            "plan4",
                            "plan5",
                            "postgraduate"
                          ]
                        },
                        "maxItems": 10
                      },
                      "pension": {
                        "type": "object",
                        "properties": {
                          "type": {
                            "type": "string",
                            "enum": [
                              "percent",
                              "fixed"
                            ]
                          },
                          "value": {
                            "type": "number",
                            "minimum": 0,
                            "maximum": 1000000000
                          },
                          "relief": {
                            "type": "string",
                            "enum": [
                              "net",
                              "gross",
                              "net_pay"
                            ]
                          }
                        },
                        "required": [
                          "type",
                          "value",
                          "relief"
                        ],
                        "additionalProperties": false
                      },
                      "childrenCount": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 100
                      },
                      "married": {
                        "type": "boolean"
                      },
                      "partnerIncome": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 1000000000
                      },
                      "blind": {
                        "type": "boolean"
                      },
                      "noNI": {
                        "type": "boolean"
                      },
                      "bonus": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 1000000000
                      },
                      "additionalAllowances": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 1000000000
                      },
                      "hoursPerWeek": {
                        "type": "number",
                        "exclusiveMinimum": 0,
                        "maximum": 168
                      },
                      "salarySacrifice": {
                        "type": "array",
                        "items": {
                          "oneOf": [
                            {
                              "type": "object",
                              "properties": {
                                "scheme": {
                                  "type": "string",
                                  "enum": [
                                    "cycle_to_work"
                                  ]
                                },
                                "amount": {
                                  "type": "number",
                                  "minimum": 0,
                                  "maximum": 1000000000
                                }
                              },
                              "required": [
                                "scheme",
                                "amount"
                              ],
                              "additionalProperties": false
                            },
                            {
                              "type": "object",
                              "properties": {
                                "scheme": {
                                  "type": "string",
                                  "enum": [
                                    "holiday_buy"
                                  ]
                                },
                                "amount": {
                                  "type": "number",
                                  "minimum": 0,
                                  "maximum": 1000000000
                                },
                                "days": {
                                  "type": "number",
                                  "minimum": 0
                                }
                              },
                              "required": [
                                "scheme",
                                "amount"
                              ],
                              "additionalProperties": false
                            },
                            {
                              "type": "object",
                              "properties": {
                                "scheme": {
                                  "type": "string",
                                  "enum": [
                                    "ev_car"
                                  ]
                                },
                                "amount": {
                                  "type": "number",
                                  "minimum": 0,
                                  "maximum": 1000000000
                                },
                                "monthlyAmount": {
                                  "type": "number",
                                  "minimum": 0
                                },
                                "leaseMonths": {
                                  "type": "number",
                                  "minimum": 0
                                },
                                "p11dValue": {
                                  "type": "number",
                                  "minimum": 0,
                                  "maximum": 1000000000
                                }
                              },
                              "required": [
                                "scheme",
                                "amount"
                              ],
                              "additionalProperties": false
                            },
                            {
                              "type": "object",
                              "properties": {
                                "scheme": {
                                  "type": "string",
                                  "enum": [
                                    "pension_increase"
                                  ]
                                },
                                "amount": {
                                  "type": "number",
                                  "minimum": 0,
                                  "maximum": 1000000000
                                }
                              },
                              "required": [
                                "scheme",
                                "amount"
                              ],
                              "additionalProperties": false
                            }
                          ]
                        }
                      }
                    },
                    "required": [
                      "taxYear",
                      "region",
                      "frequency"
                    ],
                    "additionalProperties": false
                  }
                },
                "required": [
                  "targetNet",
                  "options"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful calculation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "grossIncome": {
                          "type": "number"
                        },
                        "calculation": {
                          "type": "object",
                          "properties": {
                            "inputs": {
                              "type": "object",
                              "properties": {
                                "taxYear": {
                                  "type": "string"
                                },
                                "region": {
                                  "type": "string",
                                  "enum": [
                                    "england",
                                    "wales",
                                    "scotland",
                                    "northern-ireland"
                                  ]
                                },
                                "salary": {
                                  "type": "number"
                                },
                                "frequency": {
                                  "type": "string",
                                  "enum": [
                                    "year",
                                    "month",
                                    "fourWeeks",
                                    "twoWeeks",
                                    "week",
                                    "day",
                                    "hour"
                                  ]
                                },
                                "taxCode": {
                                  "type": "string"
                                },
                                "studentLoans": {
                                  "type": "array",
                                  "items": {
                                    "type": "string"
                                  }
                                },
                                "pension": {
                                  "type": "object",
                                  "properties": {
                                    "type": {
                                      "type": "string",
                                      "enum": [
                                        "percent",
                                        "fixed"
                                      ]
                                    },
                                    "value": {
                                      "type": "number"
                                    },
                                    "relief": {
                                      "type": "string",
                                      "enum": [
                                        "net",
                                        "gross",
                                        "net_pay"
                                      ]
                                    }
                                  },
                                  "required": [
                                    "type",
                                    "value",
                                    "relief"
                                  ]
                                },
                                "personalPension": {
                                  "type": "object",
                                  "properties": {
                                    "type": {
                                      "type": "string",
                                      "enum": [
                                        "percent",
                                        "fixed"
                                      ]
                                    },
                                    "value": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "type",
                                    "value"
                                  ]
                                },
                                "childrenCount": {
                                  "type": "number"
                                },
                                "married": {
                                  "type": "boolean"
                                },
                                "partnerIncome": {
                                  "type": "number"
                                },
                                "blind": {
                                  "type": "boolean"
                                },
                                "noNI": {
                                  "type": "boolean"
                                },
                                "age": {
                                  "type": "string",
                                  "enum": [
                                    "under65",
                                    "65to74",
                                    "over75"
                                  ]
                                },
                                "overtime": {
                                  "type": "object",
                                  "properties": {
                                    "hours": {
                                      "type": "number"
                                    },
                                    "rate": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "hours",
                                    "rate"
                                  ]
                                },
                                "bonus": {
                                  "type": "number"
                                },
                                "additionalAllowances": {
                                  "type": "number"
                                },
                                "hoursPerWeek": {
                                  "type": "number"
                                },
                                "salarySacrifice": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "scheme": {
                                        "type": "string",
                                        "enum": [
                                          "cycle_to_work",
                                          "holiday_buy",
                                          "ev_car",
                                          "pension_increase"
                                        ]
                                      },
                                      "amount": {
                                        "type": "number"
                                      },
                                      "days": {
                                        "type": "number"
                                      },
                                      "monthlyAmount": {
                                        "type": "number"
                                      },
                                      "leaseMonths": {
                                        "type": "number"
                                      },
                                      "p11dValue": {
                                        "type": "number"
                                      }
                                    },
                                    "required": [
                                      "scheme",
                                      "amount"
                                    ]
                                  }
                                }
                              },
                              "required": [
                                "taxYear",
                                "region",
                                "salary",
                                "frequency"
                              ]
                            },
                            "grossAnnual": {
                              "type": "number"
                            },
                            "personalAllowance": {
                              "type": "number"
                            },
                            "taxableIncome": {
                              "type": "number"
                            },
                            "incomeTax": {
                              "type": "object",
                              "properties": {
                                "taxableIncome": {
                                  "type": "number"
                                },
                                "personalAllowance": {
                                  "type": "number"
                                },
                                "bands": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "name": {
                                        "type": "string"
                                      },
                                      "rate": {
                                        "type": "number"
                                      },
                                      "taxable": {
                                        "type": "number"
                                      },
                                      "tax": {
                                        "type": "number"
                                      }
                                    },
                                    "required": [
                                      "name",
                                      "rate",
                                      "taxable",
                                      "tax"
                                    ]
                                  }
                                },
                                "totalTax": {
                                  "type": "number"
                                },
                                "effectiveRate": {
                                  "type": "number"
                                },
                                "marginalRate": {
                                  "type": "number"
                                }
                              },
                              "required": [
                                "taxableIncome",
                                "personalAllowance",
                                "bands",
                                "totalTax",
                                "effectiveRate",
                                "marginalRate"
                              ]
                            },
                            "nationalInsurance": {
                              "type": "object",
                              "properties": {
                                "employee": {
                                  "type": "object",
                                  "properties": {
                                    "earnings": {
                                      "type": "number"
                                    },
                                    "mainContribution": {
                                      "type": "number"
                                    },
                                    "upperContribution": {
                                      "type": "number"
                                    },
                                    "totalContribution": {
                                      "type": "number"
                                    },
                                    "effectiveRate": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "earnings",
                                    "mainContribution",
                                    "upperContribution",
                                    "totalContribution",
                                    "effectiveRate"
                                  ]
                                },
                                "employer": {
                                  "type": "object",
                                  "properties": {
                                    "earnings": {
                                      "type": "number"
                                    },
                                    "contribution": {
                                      "type": "number"
                                    },
                                    "effectiveRate": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "earnings",
                                    "contribution",
                                    "effectiveRate"
                                  ]
                                }
                              },
                              "required": [
                                "employee",
                                "employer"
                              ]
                            },
                            "studentLoans": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "plan": {
                                    "type": "string"
                                  },
                                  "threshold": {
                                    "type": "number"
                                  },
                                  "rate": {
                                    "type": "number"
                                  },
                                  "repayment": {
                                    "type": "number"
                                  }
                                },
                                "required": [
                                  "plan",
                                  "threshold",
                                  "rate",
                                  "repayment"
                                ]
                              }
                            },
                            "pension": {
                              "type": "object",
                              "properties": {
                                "employeeContribution": {
                                  "type": "number"
                                },
                                "employerContribution": {
                                  "type": "number"
                                },
                                "taxRelief": {
                                  "type": "number"
                                },
                                "sacrificeAmount": {
                                  "type": "number"
                                }
                              },
                              "required": [
                                "employeeContribution",
                                "employerContribution",
                                "taxRelief",
                                "sacrificeAmount"
                              ]
                            },
                            "salarySacrifice": {
                              "type": "object",
                              "properties": {
                                "schemes": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "scheme": {
                                        "type": "string",
                                        "enum": [
                                          "cycle_to_work",
                                          "holiday_buy",
                                          "ev_car",
                                          "pension_increase"
                                        ]
                                      },
                                      "amount": {
                                        "type": "number"
                                      },
                                      "displayName": {
                                        "type": "string"
                                      },
                                      "days": {
                                        "type": "number"
                                      },
                                      "monthlyAmount": {
                                        "type": "number"
                                      },
                                      "leaseMonths": {
                                        "type": "number"
                                      },
                                      "p11dValue": {
                                        "type": "number"
                                      }
                                    },
                                    "required": [
                                      "scheme",
                                      "amount",
                                      "displayName"
                                    ]
                                  }
                                },
                                "totalSacrifice": {
                                  "type": "number"
                                },
                                "adjustedGross": {
                                  "type": "number"
                                },
                                "taxSaving": {
                                  "type": "number"
                                },
                                "niSaving": {
                                  "type": "number"
                                },
                                "benefitInKindTax": {
                                  "type": "number"
                                },
                                "effectiveSaving": {
                                  "type": "number"
                                },
                                "netCostToEmployee": {
                                  "type": "number"
                                },
                                "takeHomeChange": {
                                  "type": "number"
                                },
                                "warnings": {
                                  "type": "array",
                                  "items": {
                                    "type": "string"
                                  }
                                }
                              },
                              "required": [
                                "schemes",
                                "totalSacrifice",
                                "adjustedGross",
                                "taxSaving",
                                "niSaving",
                                "benefitInKindTax",
                                "effectiveSaving",
                                "netCostToEmployee",
                                "takeHomeChange",
                                "warnings"
                              ]
                            },
                            "childBenefit": {
                              "type": "object",
                              "properties": {
                                "weeklyBenefit": {
                                  "type": "number"
                                },
                                "annualBenefit": {
                                  "type": "number"
                                },
                                "hiChargeRate": {
                                  "type": "number"
                                },
                                "hiChargeAmount": {
                                  "type": "number"
                                },
                                "netBenefit": {
                                  "type": "number"
                                }
                              },
                              "required": [
                                "weeklyBenefit",
                                "annualBenefit",
                                "hiChargeRate",
                                "hiChargeAmount",
                                "netBenefit"
                              ]
                            },
                            "marriageAllowance": {
                              "type": "object",
                              "properties": {
                                "transferred": {
                                  "type": "number"
                                },
                                "taxSaving": {
                                  "type": "number"
                                }
                              },
                              "required": [
                                "transferred",
                                "taxSaving"
                              ]
                            },
                            "totalDeductions": {
                              "type": "number"
                            },
                            "netAnnual": {
                              "type": "number"
                            },
                            "breakdown": {
                              "type": "object",
                              "properties": {
                                "yearly": {
                                  "type": "object",
                                  "properties": {
                                    "gross": {
                                      "type": "number"
                                    },
                                    "salarySacrifice": {
                                      "type": "number"
                                    },
                                    "taxablePay": {
                                      "type": "number"
                                    },
                                    "incomeTax": {
                                      "type": "number"
                                    },
                                    "benefitInKindTax": {
                                      "type": "number"
                                    },
                                    "nationalInsurance": {
                                      "type": "number"
                                    },
                                    "studentLoan": {
                                      "type": "number"
                                    },
                                    "pension": {
                                      "type": "number"
                                    },
                                    "totalDeductions": {
                                      "type": "number"
                                    },
                                    "net": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "gross",
                                    "salarySacrifice",
                                    "taxablePay",
                                    "incomeTax",
                                    "benefitInKindTax",
                                    "nationalInsurance",
                                    "studentLoan",
                                    "pension",
                                    "totalDeductions",
                                    "net"
                                  ]
                                },
                                "monthly": {
                                  "type": "object",
                                  "properties": {
                                    "gross": {
                                      "type": "number"
                                    },
                                    "salarySacrifice": {
                                      "type": "number"
                                    },
                                    "taxablePay": {
                                      "type": "number"
                                    },
                                    "incomeTax": {
                                      "type": "number"
                                    },
                                    "benefitInKindTax": {
                                      "type": "number"
                                    },
                                    "nationalInsurance": {
                                      "type": "number"
                                    },
                                    "studentLoan": {
                                      "type": "number"
                                    },
                                    "pension": {
                                      "type": "number"
                                    },
                                    "totalDeductions": {
                                      "type": "number"
                                    },
                                    "net": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "gross",
                                    "salarySacrifice",
                                    "taxablePay",
                                    "incomeTax",
                                    "benefitInKindTax",
                                    "nationalInsurance",
                                    "studentLoan",
                                    "pension",
                                    "totalDeductions",
                                    "net"
                                  ]
                                },
                                "fourWeekly": {
                                  "type": "object",
                                  "properties": {
                                    "gross": {
                                      "type": "number"
                                    },
                                    "salarySacrifice": {
                                      "type": "number"
                                    },
                                    "taxablePay": {
                                      "type": "number"
                                    },
                                    "incomeTax": {
                                      "type": "number"
                                    },
                                    "benefitInKindTax": {
                                      "type": "number"
                                    },
                                    "nationalInsurance": {
                                      "type": "number"
                                    },
                                    "studentLoan": {
                                      "type": "number"
                                    },
                                    "pension": {
                                      "type": "number"
                                    },
                                    "totalDeductions": {
                                      "type": "number"
                                    },
                                    "net": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "gross",
                                    "salarySacrifice",
                                    "taxablePay",
                                    "incomeTax",
                                    "benefitInKindTax",
                                    "nationalInsurance",
                                    "studentLoan",
                                    "pension",
                                    "totalDeductions",
                                    "net"
                                  ]
                                },
                                "twoWeekly": {
                                  "type": "object",
                                  "properties": {
                                    "gross": {
                                      "type": "number"
                                    },
                                    "salarySacrifice": {
                                      "type": "number"
                                    },
                                    "taxablePay": {
                                      "type": "number"
                                    },
                                    "incomeTax": {
                                      "type": "number"
                                    },
                                    "benefitInKindTax": {
                                      "type": "number"
                                    },
                                    "nationalInsurance": {
                                      "type": "number"
                                    },
                                    "studentLoan": {
                                      "type": "number"
                                    },
                                    "pension": {
                                      "type": "number"
                                    },
                                    "totalDeductions": {
                                      "type": "number"
                                    },
                                    "net": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "gross",
                                    "salarySacrifice",
                                    "taxablePay",
                                    "incomeTax",
                                    "benefitInKindTax",
                                    "nationalInsurance",
                                    "studentLoan",
                                    "pension",
                                    "totalDeductions",
                                    "net"
                                  ]
                                },
                                "weekly": {
                                  "type": "object",
                                  "properties": {
                                    "gross": {
                                      "type": "number"
                                    },
                                    "salarySacrifice": {
                                      "type": "number"
                                    },
                                    "taxablePay": {
                                      "type": "number"
                                    },
                                    "incomeTax": {
                                      "type": "number"
                                    },
                                    "benefitInKindTax": {
                                      "type": "number"
                                    },
                                    "nationalInsurance": {
                                      "type": "number"
                                    },
                                    "studentLoan": {
                                      "type": "number"
                                    },
                                    "pension": {
                                      "type": "number"
                                    },
                                    "totalDeductions": {
                                      "type": "number"
                                    },
                                    "net": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "gross",
                                    "salarySacrifice",
                                    "taxablePay",
                                    "incomeTax",
                                    "benefitInKindTax",
                                    "nationalInsurance",
                                    "studentLoan",
                                    "pension",
                                    "totalDeductions",
                                    "net"
                                  ]
                                },
                                "daily": {
                                  "type": "object",
                                  "properties": {
                                    "gross": {
                                      "type": "number"
                                    },
                                    "salarySacrifice": {
                                      "type": "number"
                                    },
                                    "taxablePay": {
                                      "type": "number"
                                    },
                                    "incomeTax": {
                                      "type": "number"
                                    },
                                    "benefitInKindTax": {
                                      "type": "number"
                                    },
                                    "nationalInsurance": {
                                      "type": "number"
                                    },
                                    "studentLoan": {
                                      "type": "number"
                                    },
                                    "pension": {
                                      "type": "number"
                                    },
                                    "totalDeductions": {
                                      "type": "number"
                                    },
                                    "net": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "gross",
                                    "salarySacrifice",
                                    "taxablePay",
                                    "incomeTax",
                                    "benefitInKindTax",
                                    "nationalInsurance",
                                    "studentLoan",
                                    "pension",
                                    "totalDeductions",
                                    "net"
                                  ]
                                },
                                "hourly": {
                                  "type": "object",
                                  "properties": {
                                    "gross": {
                                      "type": "number"
                                    },
                                    "salarySacrifice": {
                                      "type": "number"
                                    },
                                    "taxablePay": {
                                      "type": "number"
                                    },
                                    "incomeTax": {
                                      "type": "number"
                                    },
                                    "benefitInKindTax": {
                                      "type": "number"
                                    },
                                    "nationalInsurance": {
                                      "type": "number"
                                    },
                                    "studentLoan": {
                                      "type": "number"
                                    },
                                    "pension": {
                                      "type": "number"
                                    },
                                    "totalDeductions": {
                                      "type": "number"
                                    },
                                    "net": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "gross",
                                    "salarySacrifice",
                                    "taxablePay",
                                    "incomeTax",
                                    "benefitInKindTax",
                                    "nationalInsurance",
                                    "studentLoan",
                                    "pension",
                                    "totalDeductions",
                                    "net"
                                  ]
                                }
                              },
                              "required": [
                                "yearly",
                                "monthly",
                                "fourWeekly",
                                "twoWeekly",
                                "weekly",
                                "daily",
                                "hourly"
                              ]
                            },
                            "effectiveTaxRate": {
                              "type": "number"
                            },
                            "marginalTaxRate": {
                              "type": "number"
                            },
                            "previousYear": {
                              "type": "object",
                              "properties": {
                                "netAnnual": {
                                  "type": "number"
                                },
                                "difference": {
                                  "type": "number"
                                },
                                "differenceMonthly": {
                                  "type": "number"
                                }
                              },
                              "required": [
                                "netAnnual",
                                "difference",
                                "differenceMonthly"
                              ]
                            }
                          },
                          "required": [
                            "inputs",
                            "grossAnnual",
                            "personalAllowance",
                            "taxableIncome",
                            "incomeTax",
                            "nationalInsurance",
                            "studentLoans",
                            "pension",
                            "salarySacrifice",
                            "totalDeductions",
                            "netAnnual",
                            "breakdown",
                            "effectiveTaxRate",
                            "marginalTaxRate"
                          ]
                        }
                      },
                      "required": [
                        "grossIncome",
                        "calculation"
                      ]
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "version": {
                          "type": "string"
                        },
                        "taxYear": {
                          "type": "string"
                        },
                        "calculatedAt": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "version",
                        "taxYear",
                        "calculatedAt"
                      ]
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Validation error (VALIDATION_ERROR) or malformed JSON (INVALID_JSON)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "API key is invalid, disabled, or expired (INVALID_KEY)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Search ended before reaching the take-home target (CALCULATION_LIMIT)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded (RATE_LIMITED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Auth or rate limiting not configured (AUTH_UNAVAILABLE, SERVICE_UNAVAILABLE)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/pro-rata": {
      "post": {
        "summary": "Pro-rata salary calculator",
        "description": "Estimates pro-rata gross pay. For date ranges, any calculation or net-difference fields are annual illustrations of that gross amount, not take-home for the period.",
        "operationId": "proRata",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "fteSalary": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 1000000000
                  },
                  "mode": {
                    "type": "string",
                    "enum": [
                      "hours",
                      "days",
                      "daysPerWeek",
                      "dates"
                    ]
                  },
                  "actualHours": {
                    "type": "number",
                    "minimum": 0
                  },
                  "fteHours": {
                    "type": "number",
                    "minimum": 0
                  },
                  "daysWorked": {
                    "type": "number",
                    "minimum": 0
                  },
                  "totalWorkingDays": {
                    "type": "number",
                    "minimum": 0
                  },
                  "weeklyDays": {
                    "type": "number",
                    "minimum": 0
                  },
                  "fteWeeklyDays": {
                    "type": "number",
                    "minimum": 0
                  },
                  "startDate": {
                    "type": "string",
                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                  },
                  "endDate": {
                    "type": "string",
                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                  },
                  "taxYear": {
                    "type": "string",
                    "enum": [
                      "2024-25",
                      "2025-26",
                      "2026-27"
                    ]
                  },
                  "region": {
                    "type": "string",
                    "enum": [
                      "england",
                      "wales",
                      "scotland",
                      "northern-ireland"
                    ]
                  },
                  "taxCode": {
                    "type": "string",
                    "maxLength": 20
                  },
                  "studentLoans": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "plan1",
                        "plan2",
                        "plan4",
                        "plan5",
                        "postgraduate"
                      ]
                    },
                    "maxItems": 10
                  },
                  "pension": {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "percent",
                          "fixed"
                        ]
                      },
                      "value": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 1000000000
                      },
                      "relief": {
                        "type": "string",
                        "enum": [
                          "net",
                          "gross",
                          "net_pay"
                        ]
                      }
                    },
                    "required": [
                      "type",
                      "value",
                      "relief"
                    ],
                    "additionalProperties": false
                  }
                },
                "required": [
                  "fteSalary",
                  "mode",
                  "taxYear",
                  "region"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful calculation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "calculationBasis": {
                          "type": "string"
                        },
                        "proRataSalary": {
                          "type": "number"
                        },
                        "fteSalary": {
                          "type": "number"
                        },
                        "proRataFraction": {
                          "type": "number"
                        },
                        "proRataCalculation": {
                          "type": "object",
                          "properties": {
                            "inputs": {
                              "type": "object",
                              "properties": {
                                "taxYear": {
                                  "type": "string"
                                },
                                "region": {
                                  "type": "string",
                                  "enum": [
                                    "england",
                                    "wales",
                                    "scotland",
                                    "northern-ireland"
                                  ]
                                },
                                "salary": {
                                  "type": "number"
                                },
                                "frequency": {
                                  "type": "string",
                                  "enum": [
                                    "year",
                                    "month",
                                    "fourWeeks",
                                    "twoWeeks",
                                    "week",
                                    "day",
                                    "hour"
                                  ]
                                },
                                "taxCode": {
                                  "type": "string"
                                },
                                "studentLoans": {
                                  "type": "array",
                                  "items": {
                                    "type": "string"
                                  }
                                },
                                "pension": {
                                  "type": "object",
                                  "properties": {
                                    "type": {
                                      "type": "string",
                                      "enum": [
                                        "percent",
                                        "fixed"
                                      ]
                                    },
                                    "value": {
                                      "type": "number"
                                    },
                                    "relief": {
                                      "type": "string",
                                      "enum": [
                                        "net",
                                        "gross",
                                        "net_pay"
                                      ]
                                    }
                                  },
                                  "required": [
                                    "type",
                                    "value",
                                    "relief"
                                  ]
                                },
                                "personalPension": {
                                  "type": "object",
                                  "properties": {
                                    "type": {
                                      "type": "string",
                                      "enum": [
                                        "percent",
                                        "fixed"
                                      ]
                                    },
                                    "value": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "type",
                                    "value"
                                  ]
                                },
                                "childrenCount": {
                                  "type": "number"
                                },
                                "married": {
                                  "type": "boolean"
                                },
                                "partnerIncome": {
                                  "type": "number"
                                },
                                "blind": {
                                  "type": "boolean"
                                },
                                "noNI": {
                                  "type": "boolean"
                                },
                                "age": {
                                  "type": "string",
                                  "enum": [
                                    "under65",
                                    "65to74",
                                    "over75"
                                  ]
                                },
                                "overtime": {
                                  "type": "object",
                                  "properties": {
                                    "hours": {
                                      "type": "number"
                                    },
                                    "rate": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "hours",
                                    "rate"
                                  ]
                                },
                                "bonus": {
                                  "type": "number"
                                },
                                "additionalAllowances": {
                                  "type": "number"
                                },
                                "hoursPerWeek": {
                                  "type": "number"
                                },
                                "salarySacrifice": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "scheme": {
                                        "type": "string",
                                        "enum": [
                                          "cycle_to_work",
                                          "holiday_buy",
                                          "ev_car",
                                          "pension_increase"
                                        ]
                                      },
                                      "amount": {
                                        "type": "number"
                                      },
                                      "days": {
                                        "type": "number"
                                      },
                                      "monthlyAmount": {
                                        "type": "number"
                                      },
                                      "leaseMonths": {
                                        "type": "number"
                                      },
                                      "p11dValue": {
                                        "type": "number"
                                      }
                                    },
                                    "required": [
                                      "scheme",
                                      "amount"
                                    ]
                                  }
                                }
                              },
                              "required": [
                                "taxYear",
                                "region",
                                "salary",
                                "frequency"
                              ]
                            },
                            "grossAnnual": {
                              "type": "number"
                            },
                            "personalAllowance": {
                              "type": "number"
                            },
                            "taxableIncome": {
                              "type": "number"
                            },
                            "incomeTax": {
                              "type": "object",
                              "properties": {
                                "taxableIncome": {
                                  "type": "number"
                                },
                                "personalAllowance": {
                                  "type": "number"
                                },
                                "bands": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "name": {
                                        "type": "string"
                                      },
                                      "rate": {
                                        "type": "number"
                                      },
                                      "taxable": {
                                        "type": "number"
                                      },
                                      "tax": {
                                        "type": "number"
                                      }
                                    },
                                    "required": [
                                      "name",
                                      "rate",
                                      "taxable",
                                      "tax"
                                    ]
                                  }
                                },
                                "totalTax": {
                                  "type": "number"
                                },
                                "effectiveRate": {
                                  "type": "number"
                                },
                                "marginalRate": {
                                  "type": "number"
                                }
                              },
                              "required": [
                                "taxableIncome",
                                "personalAllowance",
                                "bands",
                                "totalTax",
                                "effectiveRate",
                                "marginalRate"
                              ]
                            },
                            "nationalInsurance": {
                              "type": "object",
                              "properties": {
                                "employee": {
                                  "type": "object",
                                  "properties": {
                                    "earnings": {
                                      "type": "number"
                                    },
                                    "mainContribution": {
                                      "type": "number"
                                    },
                                    "upperContribution": {
                                      "type": "number"
                                    },
                                    "totalContribution": {
                                      "type": "number"
                                    },
                                    "effectiveRate": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "earnings",
                                    "mainContribution",
                                    "upperContribution",
                                    "totalContribution",
                                    "effectiveRate"
                                  ]
                                },
                                "employer": {
                                  "type": "object",
                                  "properties": {
                                    "earnings": {
                                      "type": "number"
                                    },
                                    "contribution": {
                                      "type": "number"
                                    },
                                    "effectiveRate": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "earnings",
                                    "contribution",
                                    "effectiveRate"
                                  ]
                                }
                              },
                              "required": [
                                "employee",
                                "employer"
                              ]
                            },
                            "studentLoans": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "plan": {
                                    "type": "string"
                                  },
                                  "threshold": {
                                    "type": "number"
                                  },
                                  "rate": {
                                    "type": "number"
                                  },
                                  "repayment": {
                                    "type": "number"
                                  }
                                },
                                "required": [
                                  "plan",
                                  "threshold",
                                  "rate",
                                  "repayment"
                                ]
                              }
                            },
                            "pension": {
                              "type": "object",
                              "properties": {
                                "employeeContribution": {
                                  "type": "number"
                                },
                                "employerContribution": {
                                  "type": "number"
                                },
                                "taxRelief": {
                                  "type": "number"
                                },
                                "sacrificeAmount": {
                                  "type": "number"
                                }
                              },
                              "required": [
                                "employeeContribution",
                                "employerContribution",
                                "taxRelief",
                                "sacrificeAmount"
                              ]
                            },
                            "salarySacrifice": {
                              "type": "object",
                              "properties": {
                                "schemes": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "scheme": {
                                        "type": "string",
                                        "enum": [
                                          "cycle_to_work",
                                          "holiday_buy",
                                          "ev_car",
                                          "pension_increase"
                                        ]
                                      },
                                      "amount": {
                                        "type": "number"
                                      },
                                      "displayName": {
                                        "type": "string"
                                      },
                                      "days": {
                                        "type": "number"
                                      },
                                      "monthlyAmount": {
                                        "type": "number"
                                      },
                                      "leaseMonths": {
                                        "type": "number"
                                      },
                                      "p11dValue": {
                                        "type": "number"
                                      }
                                    },
                                    "required": [
                                      "scheme",
                                      "amount",
                                      "displayName"
                                    ]
                                  }
                                },
                                "totalSacrifice": {
                                  "type": "number"
                                },
                                "adjustedGross": {
                                  "type": "number"
                                },
                                "taxSaving": {
                                  "type": "number"
                                },
                                "niSaving": {
                                  "type": "number"
                                },
                                "benefitInKindTax": {
                                  "type": "number"
                                },
                                "effectiveSaving": {
                                  "type": "number"
                                },
                                "netCostToEmployee": {
                                  "type": "number"
                                },
                                "takeHomeChange": {
                                  "type": "number"
                                },
                                "warnings": {
                                  "type": "array",
                                  "items": {
                                    "type": "string"
                                  }
                                }
                              },
                              "required": [
                                "schemes",
                                "totalSacrifice",
                                "adjustedGross",
                                "taxSaving",
                                "niSaving",
                                "benefitInKindTax",
                                "effectiveSaving",
                                "netCostToEmployee",
                                "takeHomeChange",
                                "warnings"
                              ]
                            },
                            "childBenefit": {
                              "type": "object",
                              "properties": {
                                "weeklyBenefit": {
                                  "type": "number"
                                },
                                "annualBenefit": {
                                  "type": "number"
                                },
                                "hiChargeRate": {
                                  "type": "number"
                                },
                                "hiChargeAmount": {
                                  "type": "number"
                                },
                                "netBenefit": {
                                  "type": "number"
                                }
                              },
                              "required": [
                                "weeklyBenefit",
                                "annualBenefit",
                                "hiChargeRate",
                                "hiChargeAmount",
                                "netBenefit"
                              ]
                            },
                            "marriageAllowance": {
                              "type": "object",
                              "properties": {
                                "transferred": {
                                  "type": "number"
                                },
                                "taxSaving": {
                                  "type": "number"
                                }
                              },
                              "required": [
                                "transferred",
                                "taxSaving"
                              ]
                            },
                            "totalDeductions": {
                              "type": "number"
                            },
                            "netAnnual": {
                              "type": "number"
                            },
                            "breakdown": {
                              "type": "object",
                              "properties": {
                                "yearly": {
                                  "type": "object",
                                  "properties": {
                                    "gross": {
                                      "type": "number"
                                    },
                                    "salarySacrifice": {
                                      "type": "number"
                                    },
                                    "taxablePay": {
                                      "type": "number"
                                    },
                                    "incomeTax": {
                                      "type": "number"
                                    },
                                    "benefitInKindTax": {
                                      "type": "number"
                                    },
                                    "nationalInsurance": {
                                      "type": "number"
                                    },
                                    "studentLoan": {
                                      "type": "number"
                                    },
                                    "pension": {
                                      "type": "number"
                                    },
                                    "totalDeductions": {
                                      "type": "number"
                                    },
                                    "net": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "gross",
                                    "salarySacrifice",
                                    "taxablePay",
                                    "incomeTax",
                                    "benefitInKindTax",
                                    "nationalInsurance",
                                    "studentLoan",
                                    "pension",
                                    "totalDeductions",
                                    "net"
                                  ]
                                },
                                "monthly": {
                                  "type": "object",
                                  "properties": {
                                    "gross": {
                                      "type": "number"
                                    },
                                    "salarySacrifice": {
                                      "type": "number"
                                    },
                                    "taxablePay": {
                                      "type": "number"
                                    },
                                    "incomeTax": {
                                      "type": "number"
                                    },
                                    "benefitInKindTax": {
                                      "type": "number"
                                    },
                                    "nationalInsurance": {
                                      "type": "number"
                                    },
                                    "studentLoan": {
                                      "type": "number"
                                    },
                                    "pension": {
                                      "type": "number"
                                    },
                                    "totalDeductions": {
                                      "type": "number"
                                    },
                                    "net": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "gross",
                                    "salarySacrifice",
                                    "taxablePay",
                                    "incomeTax",
                                    "benefitInKindTax",
                                    "nationalInsurance",
                                    "studentLoan",
                                    "pension",
                                    "totalDeductions",
                                    "net"
                                  ]
                                },
                                "fourWeekly": {
                                  "type": "object",
                                  "properties": {
                                    "gross": {
                                      "type": "number"
                                    },
                                    "salarySacrifice": {
                                      "type": "number"
                                    },
                                    "taxablePay": {
                                      "type": "number"
                                    },
                                    "incomeTax": {
                                      "type": "number"
                                    },
                                    "benefitInKindTax": {
                                      "type": "number"
                                    },
                                    "nationalInsurance": {
                                      "type": "number"
                                    },
                                    "studentLoan": {
                                      "type": "number"
                                    },
                                    "pension": {
                                      "type": "number"
                                    },
                                    "totalDeductions": {
                                      "type": "number"
                                    },
                                    "net": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "gross",
                                    "salarySacrifice",
                                    "taxablePay",
                                    "incomeTax",
                                    "benefitInKindTax",
                                    "nationalInsurance",
                                    "studentLoan",
                                    "pension",
                                    "totalDeductions",
                                    "net"
                                  ]
                                },
                                "twoWeekly": {
                                  "type": "object",
                                  "properties": {
                                    "gross": {
                                      "type": "number"
                                    },
                                    "salarySacrifice": {
                                      "type": "number"
                                    },
                                    "taxablePay": {
                                      "type": "number"
                                    },
                                    "incomeTax": {
                                      "type": "number"
                                    },
                                    "benefitInKindTax": {
                                      "type": "number"
                                    },
                                    "nationalInsurance": {
                                      "type": "number"
                                    },
                                    "studentLoan": {
                                      "type": "number"
                                    },
                                    "pension": {
                                      "type": "number"
                                    },
                                    "totalDeductions": {
                                      "type": "number"
                                    },
                                    "net": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "gross",
                                    "salarySacrifice",
                                    "taxablePay",
                                    "incomeTax",
                                    "benefitInKindTax",
                                    "nationalInsurance",
                                    "studentLoan",
                                    "pension",
                                    "totalDeductions",
                                    "net"
                                  ]
                                },
                                "weekly": {
                                  "type": "object",
                                  "properties": {
                                    "gross": {
                                      "type": "number"
                                    },
                                    "salarySacrifice": {
                                      "type": "number"
                                    },
                                    "taxablePay": {
                                      "type": "number"
                                    },
                                    "incomeTax": {
                                      "type": "number"
                                    },
                                    "benefitInKindTax": {
                                      "type": "number"
                                    },
                                    "nationalInsurance": {
                                      "type": "number"
                                    },
                                    "studentLoan": {
                                      "type": "number"
                                    },
                                    "pension": {
                                      "type": "number"
                                    },
                                    "totalDeductions": {
                                      "type": "number"
                                    },
                                    "net": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "gross",
                                    "salarySacrifice",
                                    "taxablePay",
                                    "incomeTax",
                                    "benefitInKindTax",
                                    "nationalInsurance",
                                    "studentLoan",
                                    "pension",
                                    "totalDeductions",
                                    "net"
                                  ]
                                },
                                "daily": {
                                  "type": "object",
                                  "properties": {
                                    "gross": {
                                      "type": "number"
                                    },
                                    "salarySacrifice": {
                                      "type": "number"
                                    },
                                    "taxablePay": {
                                      "type": "number"
                                    },
                                    "incomeTax": {
                                      "type": "number"
                                    },
                                    "benefitInKindTax": {
                                      "type": "number"
                                    },
                                    "nationalInsurance": {
                                      "type": "number"
                                    },
                                    "studentLoan": {
                                      "type": "number"
                                    },
                                    "pension": {
                                      "type": "number"
                                    },
                                    "totalDeductions": {
                                      "type": "number"
                                    },
                                    "net": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "gross",
                                    "salarySacrifice",
                                    "taxablePay",
                                    "incomeTax",
                                    "benefitInKindTax",
                                    "nationalInsurance",
                                    "studentLoan",
                                    "pension",
                                    "totalDeductions",
                                    "net"
                                  ]
                                },
                                "hourly": {
                                  "type": "object",
                                  "properties": {
                                    "gross": {
                                      "type": "number"
                                    },
                                    "salarySacrifice": {
                                      "type": "number"
                                    },
                                    "taxablePay": {
                                      "type": "number"
                                    },
                                    "incomeTax": {
                                      "type": "number"
                                    },
                                    "benefitInKindTax": {
                                      "type": "number"
                                    },
                                    "nationalInsurance": {
                                      "type": "number"
                                    },
                                    "studentLoan": {
                                      "type": "number"
                                    },
                                    "pension": {
                                      "type": "number"
                                    },
                                    "totalDeductions": {
                                      "type": "number"
                                    },
                                    "net": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "gross",
                                    "salarySacrifice",
                                    "taxablePay",
                                    "incomeTax",
                                    "benefitInKindTax",
                                    "nationalInsurance",
                                    "studentLoan",
                                    "pension",
                                    "totalDeductions",
                                    "net"
                                  ]
                                }
                              },
                              "required": [
                                "yearly",
                                "monthly",
                                "fourWeekly",
                                "twoWeekly",
                                "weekly",
                                "daily",
                                "hourly"
                              ]
                            },
                            "effectiveTaxRate": {
                              "type": "number"
                            },
                            "marginalTaxRate": {
                              "type": "number"
                            },
                            "previousYear": {
                              "type": "object",
                              "properties": {
                                "netAnnual": {
                                  "type": "number"
                                },
                                "difference": {
                                  "type": "number"
                                },
                                "differenceMonthly": {
                                  "type": "number"
                                }
                              },
                              "required": [
                                "netAnnual",
                                "difference",
                                "differenceMonthly"
                              ]
                            }
                          },
                          "required": [
                            "inputs",
                            "grossAnnual",
                            "personalAllowance",
                            "taxableIncome",
                            "incomeTax",
                            "nationalInsurance",
                            "studentLoans",
                            "pension",
                            "salarySacrifice",
                            "totalDeductions",
                            "netAnnual",
                            "breakdown",
                            "effectiveTaxRate",
                            "marginalTaxRate"
                          ]
                        },
                        "fteCalculation": {
                          "type": "object",
                          "properties": {
                            "inputs": {
                              "type": "object",
                              "properties": {
                                "taxYear": {
                                  "type": "string"
                                },
                                "region": {
                                  "type": "string",
                                  "enum": [
                                    "england",
                                    "wales",
                                    "scotland",
                                    "northern-ireland"
                                  ]
                                },
                                "salary": {
                                  "type": "number"
                                },
                                "frequency": {
                                  "type": "string",
                                  "enum": [
                                    "year",
                                    "month",
                                    "fourWeeks",
                                    "twoWeeks",
                                    "week",
                                    "day",
                                    "hour"
                                  ]
                                },
                                "taxCode": {
                                  "type": "string"
                                },
                                "studentLoans": {
                                  "type": "array",
                                  "items": {
                                    "type": "string"
                                  }
                                },
                                "pension": {
                                  "type": "object",
                                  "properties": {
                                    "type": {
                                      "type": "string",
                                      "enum": [
                                        "percent",
                                        "fixed"
                                      ]
                                    },
                                    "value": {
                                      "type": "number"
                                    },
                                    "relief": {
                                      "type": "string",
                                      "enum": [
                                        "net",
                                        "gross",
                                        "net_pay"
                                      ]
                                    }
                                  },
                                  "required": [
                                    "type",
                                    "value",
                                    "relief"
                                  ]
                                },
                                "personalPension": {
                                  "type": "object",
                                  "properties": {
                                    "type": {
                                      "type": "string",
                                      "enum": [
                                        "percent",
                                        "fixed"
                                      ]
                                    },
                                    "value": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "type",
                                    "value"
                                  ]
                                },
                                "childrenCount": {
                                  "type": "number"
                                },
                                "married": {
                                  "type": "boolean"
                                },
                                "partnerIncome": {
                                  "type": "number"
                                },
                                "blind": {
                                  "type": "boolean"
                                },
                                "noNI": {
                                  "type": "boolean"
                                },
                                "age": {
                                  "type": "string",
                                  "enum": [
                                    "under65",
                                    "65to74",
                                    "over75"
                                  ]
                                },
                                "overtime": {
                                  "type": "object",
                                  "properties": {
                                    "hours": {
                                      "type": "number"
                                    },
                                    "rate": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "hours",
                                    "rate"
                                  ]
                                },
                                "bonus": {
                                  "type": "number"
                                },
                                "additionalAllowances": {
                                  "type": "number"
                                },
                                "hoursPerWeek": {
                                  "type": "number"
                                },
                                "salarySacrifice": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "scheme": {
                                        "type": "string",
                                        "enum": [
                                          "cycle_to_work",
                                          "holiday_buy",
                                          "ev_car",
                                          "pension_increase"
                                        ]
                                      },
                                      "amount": {
                                        "type": "number"
                                      },
                                      "days": {
                                        "type": "number"
                                      },
                                      "monthlyAmount": {
                                        "type": "number"
                                      },
                                      "leaseMonths": {
                                        "type": "number"
                                      },
                                      "p11dValue": {
                                        "type": "number"
                                      }
                                    },
                                    "required": [
                                      "scheme",
                                      "amount"
                                    ]
                                  }
                                }
                              },
                              "required": [
                                "taxYear",
                                "region",
                                "salary",
                                "frequency"
                              ]
                            },
                            "grossAnnual": {
                              "type": "number"
                            },
                            "personalAllowance": {
                              "type": "number"
                            },
                            "taxableIncome": {
                              "type": "number"
                            },
                            "incomeTax": {
                              "type": "object",
                              "properties": {
                                "taxableIncome": {
                                  "type": "number"
                                },
                                "personalAllowance": {
                                  "type": "number"
                                },
                                "bands": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "name": {
                                        "type": "string"
                                      },
                                      "rate": {
                                        "type": "number"
                                      },
                                      "taxable": {
                                        "type": "number"
                                      },
                                      "tax": {
                                        "type": "number"
                                      }
                                    },
                                    "required": [
                                      "name",
                                      "rate",
                                      "taxable",
                                      "tax"
                                    ]
                                  }
                                },
                                "totalTax": {
                                  "type": "number"
                                },
                                "effectiveRate": {
                                  "type": "number"
                                },
                                "marginalRate": {
                                  "type": "number"
                                }
                              },
                              "required": [
                                "taxableIncome",
                                "personalAllowance",
                                "bands",
                                "totalTax",
                                "effectiveRate",
                                "marginalRate"
                              ]
                            },
                            "nationalInsurance": {
                              "type": "object",
                              "properties": {
                                "employee": {
                                  "type": "object",
                                  "properties": {
                                    "earnings": {
                                      "type": "number"
                                    },
                                    "mainContribution": {
                                      "type": "number"
                                    },
                                    "upperContribution": {
                                      "type": "number"
                                    },
                                    "totalContribution": {
                                      "type": "number"
                                    },
                                    "effectiveRate": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "earnings",
                                    "mainContribution",
                                    "upperContribution",
                                    "totalContribution",
                                    "effectiveRate"
                                  ]
                                },
                                "employer": {
                                  "type": "object",
                                  "properties": {
                                    "earnings": {
                                      "type": "number"
                                    },
                                    "contribution": {
                                      "type": "number"
                                    },
                                    "effectiveRate": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "earnings",
                                    "contribution",
                                    "effectiveRate"
                                  ]
                                }
                              },
                              "required": [
                                "employee",
                                "employer"
                              ]
                            },
                            "studentLoans": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "plan": {
                                    "type": "string"
                                  },
                                  "threshold": {
                                    "type": "number"
                                  },
                                  "rate": {
                                    "type": "number"
                                  },
                                  "repayment": {
                                    "type": "number"
                                  }
                                },
                                "required": [
                                  "plan",
                                  "threshold",
                                  "rate",
                                  "repayment"
                                ]
                              }
                            },
                            "pension": {
                              "type": "object",
                              "properties": {
                                "employeeContribution": {
                                  "type": "number"
                                },
                                "employerContribution": {
                                  "type": "number"
                                },
                                "taxRelief": {
                                  "type": "number"
                                },
                                "sacrificeAmount": {
                                  "type": "number"
                                }
                              },
                              "required": [
                                "employeeContribution",
                                "employerContribution",
                                "taxRelief",
                                "sacrificeAmount"
                              ]
                            },
                            "salarySacrifice": {
                              "type": "object",
                              "properties": {
                                "schemes": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "scheme": {
                                        "type": "string",
                                        "enum": [
                                          "cycle_to_work",
                                          "holiday_buy",
                                          "ev_car",
                                          "pension_increase"
                                        ]
                                      },
                                      "amount": {
                                        "type": "number"
                                      },
                                      "displayName": {
                                        "type": "string"
                                      },
                                      "days": {
                                        "type": "number"
                                      },
                                      "monthlyAmount": {
                                        "type": "number"
                                      },
                                      "leaseMonths": {
                                        "type": "number"
                                      },
                                      "p11dValue": {
                                        "type": "number"
                                      }
                                    },
                                    "required": [
                                      "scheme",
                                      "amount",
                                      "displayName"
                                    ]
                                  }
                                },
                                "totalSacrifice": {
                                  "type": "number"
                                },
                                "adjustedGross": {
                                  "type": "number"
                                },
                                "taxSaving": {
                                  "type": "number"
                                },
                                "niSaving": {
                                  "type": "number"
                                },
                                "benefitInKindTax": {
                                  "type": "number"
                                },
                                "effectiveSaving": {
                                  "type": "number"
                                },
                                "netCostToEmployee": {
                                  "type": "number"
                                },
                                "takeHomeChange": {
                                  "type": "number"
                                },
                                "warnings": {
                                  "type": "array",
                                  "items": {
                                    "type": "string"
                                  }
                                }
                              },
                              "required": [
                                "schemes",
                                "totalSacrifice",
                                "adjustedGross",
                                "taxSaving",
                                "niSaving",
                                "benefitInKindTax",
                                "effectiveSaving",
                                "netCostToEmployee",
                                "takeHomeChange",
                                "warnings"
                              ]
                            },
                            "childBenefit": {
                              "type": "object",
                              "properties": {
                                "weeklyBenefit": {
                                  "type": "number"
                                },
                                "annualBenefit": {
                                  "type": "number"
                                },
                                "hiChargeRate": {
                                  "type": "number"
                                },
                                "hiChargeAmount": {
                                  "type": "number"
                                },
                                "netBenefit": {
                                  "type": "number"
                                }
                              },
                              "required": [
                                "weeklyBenefit",
                                "annualBenefit",
                                "hiChargeRate",
                                "hiChargeAmount",
                                "netBenefit"
                              ]
                            },
                            "marriageAllowance": {
                              "type": "object",
                              "properties": {
                                "transferred": {
                                  "type": "number"
                                },
                                "taxSaving": {
                                  "type": "number"
                                }
                              },
                              "required": [
                                "transferred",
                                "taxSaving"
                              ]
                            },
                            "totalDeductions": {
                              "type": "number"
                            },
                            "netAnnual": {
                              "type": "number"
                            },
                            "breakdown": {
                              "type": "object",
                              "properties": {
                                "yearly": {
                                  "type": "object",
                                  "properties": {
                                    "gross": {
                                      "type": "number"
                                    },
                                    "salarySacrifice": {
                                      "type": "number"
                                    },
                                    "taxablePay": {
                                      "type": "number"
                                    },
                                    "incomeTax": {
                                      "type": "number"
                                    },
                                    "benefitInKindTax": {
                                      "type": "number"
                                    },
                                    "nationalInsurance": {
                                      "type": "number"
                                    },
                                    "studentLoan": {
                                      "type": "number"
                                    },
                                    "pension": {
                                      "type": "number"
                                    },
                                    "totalDeductions": {
                                      "type": "number"
                                    },
                                    "net": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "gross",
                                    "salarySacrifice",
                                    "taxablePay",
                                    "incomeTax",
                                    "benefitInKindTax",
                                    "nationalInsurance",
                                    "studentLoan",
                                    "pension",
                                    "totalDeductions",
                                    "net"
                                  ]
                                },
                                "monthly": {
                                  "type": "object",
                                  "properties": {
                                    "gross": {
                                      "type": "number"
                                    },
                                    "salarySacrifice": {
                                      "type": "number"
                                    },
                                    "taxablePay": {
                                      "type": "number"
                                    },
                                    "incomeTax": {
                                      "type": "number"
                                    },
                                    "benefitInKindTax": {
                                      "type": "number"
                                    },
                                    "nationalInsurance": {
                                      "type": "number"
                                    },
                                    "studentLoan": {
                                      "type": "number"
                                    },
                                    "pension": {
                                      "type": "number"
                                    },
                                    "totalDeductions": {
                                      "type": "number"
                                    },
                                    "net": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "gross",
                                    "salarySacrifice",
                                    "taxablePay",
                                    "incomeTax",
                                    "benefitInKindTax",
                                    "nationalInsurance",
                                    "studentLoan",
                                    "pension",
                                    "totalDeductions",
                                    "net"
                                  ]
                                },
                                "fourWeekly": {
                                  "type": "object",
                                  "properties": {
                                    "gross": {
                                      "type": "number"
                                    },
                                    "salarySacrifice": {
                                      "type": "number"
                                    },
                                    "taxablePay": {
                                      "type": "number"
                                    },
                                    "incomeTax": {
                                      "type": "number"
                                    },
                                    "benefitInKindTax": {
                                      "type": "number"
                                    },
                                    "nationalInsurance": {
                                      "type": "number"
                                    },
                                    "studentLoan": {
                                      "type": "number"
                                    },
                                    "pension": {
                                      "type": "number"
                                    },
                                    "totalDeductions": {
                                      "type": "number"
                                    },
                                    "net": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "gross",
                                    "salarySacrifice",
                                    "taxablePay",
                                    "incomeTax",
                                    "benefitInKindTax",
                                    "nationalInsurance",
                                    "studentLoan",
                                    "pension",
                                    "totalDeductions",
                                    "net"
                                  ]
                                },
                                "twoWeekly": {
                                  "type": "object",
                                  "properties": {
                                    "gross": {
                                      "type": "number"
                                    },
                                    "salarySacrifice": {
                                      "type": "number"
                                    },
                                    "taxablePay": {
                                      "type": "number"
                                    },
                                    "incomeTax": {
                                      "type": "number"
                                    },
                                    "benefitInKindTax": {
                                      "type": "number"
                                    },
                                    "nationalInsurance": {
                                      "type": "number"
                                    },
                                    "studentLoan": {
                                      "type": "number"
                                    },
                                    "pension": {
                                      "type": "number"
                                    },
                                    "totalDeductions": {
                                      "type": "number"
                                    },
                                    "net": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "gross",
                                    "salarySacrifice",
                                    "taxablePay",
                                    "incomeTax",
                                    "benefitInKindTax",
                                    "nationalInsurance",
                                    "studentLoan",
                                    "pension",
                                    "totalDeductions",
                                    "net"
                                  ]
                                },
                                "weekly": {
                                  "type": "object",
                                  "properties": {
                                    "gross": {
                                      "type": "number"
                                    },
                                    "salarySacrifice": {
                                      "type": "number"
                                    },
                                    "taxablePay": {
                                      "type": "number"
                                    },
                                    "incomeTax": {
                                      "type": "number"
                                    },
                                    "benefitInKindTax": {
                                      "type": "number"
                                    },
                                    "nationalInsurance": {
                                      "type": "number"
                                    },
                                    "studentLoan": {
                                      "type": "number"
                                    },
                                    "pension": {
                                      "type": "number"
                                    },
                                    "totalDeductions": {
                                      "type": "number"
                                    },
                                    "net": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "gross",
                                    "salarySacrifice",
                                    "taxablePay",
                                    "incomeTax",
                                    "benefitInKindTax",
                                    "nationalInsurance",
                                    "studentLoan",
                                    "pension",
                                    "totalDeductions",
                                    "net"
                                  ]
                                },
                                "daily": {
                                  "type": "object",
                                  "properties": {
                                    "gross": {
                                      "type": "number"
                                    },
                                    "salarySacrifice": {
                                      "type": "number"
                                    },
                                    "taxablePay": {
                                      "type": "number"
                                    },
                                    "incomeTax": {
                                      "type": "number"
                                    },
                                    "benefitInKindTax": {
                                      "type": "number"
                                    },
                                    "nationalInsurance": {
                                      "type": "number"
                                    },
                                    "studentLoan": {
                                      "type": "number"
                                    },
                                    "pension": {
                                      "type": "number"
                                    },
                                    "totalDeductions": {
                                      "type": "number"
                                    },
                                    "net": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "gross",
                                    "salarySacrifice",
                                    "taxablePay",
                                    "incomeTax",
                                    "benefitInKindTax",
                                    "nationalInsurance",
                                    "studentLoan",
                                    "pension",
                                    "totalDeductions",
                                    "net"
                                  ]
                                },
                                "hourly": {
                                  "type": "object",
                                  "properties": {
                                    "gross": {
                                      "type": "number"
                                    },
                                    "salarySacrifice": {
                                      "type": "number"
                                    },
                                    "taxablePay": {
                                      "type": "number"
                                    },
                                    "incomeTax": {
                                      "type": "number"
                                    },
                                    "benefitInKindTax": {
                                      "type": "number"
                                    },
                                    "nationalInsurance": {
                                      "type": "number"
                                    },
                                    "studentLoan": {
                                      "type": "number"
                                    },
                                    "pension": {
                                      "type": "number"
                                    },
                                    "totalDeductions": {
                                      "type": "number"
                                    },
                                    "net": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "gross",
                                    "salarySacrifice",
                                    "taxablePay",
                                    "incomeTax",
                                    "benefitInKindTax",
                                    "nationalInsurance",
                                    "studentLoan",
                                    "pension",
                                    "totalDeductions",
                                    "net"
                                  ]
                                }
                              },
                              "required": [
                                "yearly",
                                "monthly",
                                "fourWeekly",
                                "twoWeekly",
                                "weekly",
                                "daily",
                                "hourly"
                              ]
                            },
                            "effectiveTaxRate": {
                              "type": "number"
                            },
                            "marginalTaxRate": {
                              "type": "number"
                            },
                            "previousYear": {
                              "type": "object",
                              "properties": {
                                "netAnnual": {
                                  "type": "number"
                                },
                                "difference": {
                                  "type": "number"
                                },
                                "differenceMonthly": {
                                  "type": "number"
                                }
                              },
                              "required": [
                                "netAnnual",
                                "difference",
                                "differenceMonthly"
                              ]
                            }
                          },
                          "required": [
                            "inputs",
                            "grossAnnual",
                            "personalAllowance",
                            "taxableIncome",
                            "incomeTax",
                            "nationalInsurance",
                            "studentLoans",
                            "pension",
                            "salarySacrifice",
                            "totalDeductions",
                            "netAnnual",
                            "breakdown",
                            "effectiveTaxRate",
                            "marginalTaxRate"
                          ]
                        },
                        "netDifference": {
                          "type": "number"
                        },
                        "netDifferenceMonthly": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "calculationBasis",
                        "proRataSalary",
                        "fteSalary",
                        "proRataFraction",
                        "proRataCalculation",
                        "fteCalculation",
                        "netDifference",
                        "netDifferenceMonthly"
                      ]
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "version": {
                          "type": "string"
                        },
                        "taxYear": {
                          "type": "string"
                        },
                        "calculatedAt": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "version",
                        "taxYear",
                        "calculatedAt"
                      ]
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Validation error (VALIDATION_ERROR) or malformed JSON (INVALID_JSON)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "API key is invalid, disabled, or expired (INVALID_KEY)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded (RATE_LIMITED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Auth or rate limiting not configured (AUTH_UNAVAILABLE, SERVICE_UNAVAILABLE)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/two-jobs": {
      "post": {
        "summary": "Two-jobs tax calculator",
        "description": "Calculates combined tax for two jobs including NI overpayment estimates.",
        "operationId": "twoJobs",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "taxYear": {
                    "type": "string",
                    "enum": [
                      "2024-25",
                      "2025-26",
                      "2026-27"
                    ]
                  },
                  "region": {
                    "type": "string",
                    "enum": [
                      "england",
                      "wales",
                      "scotland",
                      "northern-ireland"
                    ]
                  },
                  "primaryJob": {
                    "type": "object",
                    "properties": {
                      "salary": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 1000000000
                      },
                      "frequency": {
                        "type": "string",
                        "enum": [
                          "year",
                          "month",
                          "fourWeeks",
                          "twoWeeks",
                          "week",
                          "day",
                          "hour"
                        ]
                      },
                      "taxCode": {
                        "type": "string",
                        "maxLength": 20
                      },
                      "pension": {
                        "type": "object",
                        "properties": {
                          "type": {
                            "type": "string",
                            "enum": [
                              "percent",
                              "fixed"
                            ]
                          },
                          "value": {
                            "type": "number",
                            "minimum": 0,
                            "maximum": 1000000000
                          },
                          "relief": {
                            "type": "string",
                            "enum": [
                              "net",
                              "gross",
                              "net_pay"
                            ]
                          }
                        },
                        "required": [
                          "type",
                          "value",
                          "relief"
                        ],
                        "additionalProperties": false
                      },
                      "studentLoans": {
                        "type": "array",
                        "items": {
                          "type": "string",
                          "enum": [
                            "plan1",
                            "plan2",
                            "plan4",
                            "plan5",
                            "postgraduate"
                          ]
                        },
                        "maxItems": 10
                      },
                      "hoursPerWeek": {
                        "type": "number",
                        "exclusiveMinimum": 0,
                        "maximum": 168
                      }
                    },
                    "required": [
                      "salary",
                      "frequency"
                    ],
                    "additionalProperties": false
                  },
                  "secondaryJob": {
                    "type": "object",
                    "properties": {
                      "salary": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 1000000000
                      },
                      "frequency": {
                        "type": "string",
                        "enum": [
                          "year",
                          "month",
                          "fourWeeks",
                          "twoWeeks",
                          "week",
                          "day",
                          "hour"
                        ]
                      },
                      "taxCode": {
                        "type": "string",
                        "maxLength": 20
                      },
                      "pension": {
                        "type": "object",
                        "properties": {
                          "type": {
                            "type": "string",
                            "enum": [
                              "percent",
                              "fixed"
                            ]
                          },
                          "value": {
                            "type": "number",
                            "minimum": 0,
                            "maximum": 1000000000
                          },
                          "relief": {
                            "type": "string",
                            "enum": [
                              "net",
                              "gross",
                              "net_pay"
                            ]
                          }
                        },
                        "required": [
                          "type",
                          "value",
                          "relief"
                        ],
                        "additionalProperties": false
                      },
                      "studentLoans": {
                        "type": "array",
                        "items": {
                          "type": "string",
                          "enum": [
                            "plan1",
                            "plan2",
                            "plan4",
                            "plan5",
                            "postgraduate"
                          ]
                        },
                        "maxItems": 10
                      },
                      "hoursPerWeek": {
                        "type": "number",
                        "exclusiveMinimum": 0,
                        "maximum": 168
                      }
                    },
                    "required": [
                      "salary",
                      "frequency"
                    ],
                    "additionalProperties": false
                  }
                },
                "required": [
                  "taxYear",
                  "region",
                  "primaryJob",
                  "secondaryJob"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful calculation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "primary": {
                          "type": "object",
                          "properties": {
                            "inputs": {
                              "type": "object",
                              "properties": {
                                "taxYear": {
                                  "type": "string"
                                },
                                "region": {
                                  "type": "string",
                                  "enum": [
                                    "england",
                                    "wales",
                                    "scotland",
                                    "northern-ireland"
                                  ]
                                },
                                "salary": {
                                  "type": "number"
                                },
                                "frequency": {
                                  "type": "string",
                                  "enum": [
                                    "year",
                                    "month",
                                    "fourWeeks",
                                    "twoWeeks",
                                    "week",
                                    "day",
                                    "hour"
                                  ]
                                },
                                "taxCode": {
                                  "type": "string"
                                },
                                "studentLoans": {
                                  "type": "array",
                                  "items": {
                                    "type": "string"
                                  }
                                },
                                "pension": {
                                  "type": "object",
                                  "properties": {
                                    "type": {
                                      "type": "string",
                                      "enum": [
                                        "percent",
                                        "fixed"
                                      ]
                                    },
                                    "value": {
                                      "type": "number"
                                    },
                                    "relief": {
                                      "type": "string",
                                      "enum": [
                                        "net",
                                        "gross",
                                        "net_pay"
                                      ]
                                    }
                                  },
                                  "required": [
                                    "type",
                                    "value",
                                    "relief"
                                  ]
                                },
                                "personalPension": {
                                  "type": "object",
                                  "properties": {
                                    "type": {
                                      "type": "string",
                                      "enum": [
                                        "percent",
                                        "fixed"
                                      ]
                                    },
                                    "value": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "type",
                                    "value"
                                  ]
                                },
                                "childrenCount": {
                                  "type": "number"
                                },
                                "married": {
                                  "type": "boolean"
                                },
                                "partnerIncome": {
                                  "type": "number"
                                },
                                "blind": {
                                  "type": "boolean"
                                },
                                "noNI": {
                                  "type": "boolean"
                                },
                                "age": {
                                  "type": "string",
                                  "enum": [
                                    "under65",
                                    "65to74",
                                    "over75"
                                  ]
                                },
                                "overtime": {
                                  "type": "object",
                                  "properties": {
                                    "hours": {
                                      "type": "number"
                                    },
                                    "rate": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "hours",
                                    "rate"
                                  ]
                                },
                                "bonus": {
                                  "type": "number"
                                },
                                "additionalAllowances": {
                                  "type": "number"
                                },
                                "hoursPerWeek": {
                                  "type": "number"
                                },
                                "salarySacrifice": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "scheme": {
                                        "type": "string",
                                        "enum": [
                                          "cycle_to_work",
                                          "holiday_buy",
                                          "ev_car",
                                          "pension_increase"
                                        ]
                                      },
                                      "amount": {
                                        "type": "number"
                                      },
                                      "days": {
                                        "type": "number"
                                      },
                                      "monthlyAmount": {
                                        "type": "number"
                                      },
                                      "leaseMonths": {
                                        "type": "number"
                                      },
                                      "p11dValue": {
                                        "type": "number"
                                      }
                                    },
                                    "required": [
                                      "scheme",
                                      "amount"
                                    ]
                                  }
                                }
                              },
                              "required": [
                                "taxYear",
                                "region",
                                "salary",
                                "frequency"
                              ]
                            },
                            "grossAnnual": {
                              "type": "number"
                            },
                            "personalAllowance": {
                              "type": "number"
                            },
                            "taxableIncome": {
                              "type": "number"
                            },
                            "incomeTax": {
                              "type": "object",
                              "properties": {
                                "taxableIncome": {
                                  "type": "number"
                                },
                                "personalAllowance": {
                                  "type": "number"
                                },
                                "bands": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "name": {
                                        "type": "string"
                                      },
                                      "rate": {
                                        "type": "number"
                                      },
                                      "taxable": {
                                        "type": "number"
                                      },
                                      "tax": {
                                        "type": "number"
                                      }
                                    },
                                    "required": [
                                      "name",
                                      "rate",
                                      "taxable",
                                      "tax"
                                    ]
                                  }
                                },
                                "totalTax": {
                                  "type": "number"
                                },
                                "effectiveRate": {
                                  "type": "number"
                                },
                                "marginalRate": {
                                  "type": "number"
                                }
                              },
                              "required": [
                                "taxableIncome",
                                "personalAllowance",
                                "bands",
                                "totalTax",
                                "effectiveRate",
                                "marginalRate"
                              ]
                            },
                            "nationalInsurance": {
                              "type": "object",
                              "properties": {
                                "employee": {
                                  "type": "object",
                                  "properties": {
                                    "earnings": {
                                      "type": "number"
                                    },
                                    "mainContribution": {
                                      "type": "number"
                                    },
                                    "upperContribution": {
                                      "type": "number"
                                    },
                                    "totalContribution": {
                                      "type": "number"
                                    },
                                    "effectiveRate": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "earnings",
                                    "mainContribution",
                                    "upperContribution",
                                    "totalContribution",
                                    "effectiveRate"
                                  ]
                                },
                                "employer": {
                                  "type": "object",
                                  "properties": {
                                    "earnings": {
                                      "type": "number"
                                    },
                                    "contribution": {
                                      "type": "number"
                                    },
                                    "effectiveRate": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "earnings",
                                    "contribution",
                                    "effectiveRate"
                                  ]
                                }
                              },
                              "required": [
                                "employee",
                                "employer"
                              ]
                            },
                            "studentLoans": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "plan": {
                                    "type": "string"
                                  },
                                  "threshold": {
                                    "type": "number"
                                  },
                                  "rate": {
                                    "type": "number"
                                  },
                                  "repayment": {
                                    "type": "number"
                                  }
                                },
                                "required": [
                                  "plan",
                                  "threshold",
                                  "rate",
                                  "repayment"
                                ]
                              }
                            },
                            "pension": {
                              "type": "object",
                              "properties": {
                                "employeeContribution": {
                                  "type": "number"
                                },
                                "employerContribution": {
                                  "type": "number"
                                },
                                "taxRelief": {
                                  "type": "number"
                                },
                                "sacrificeAmount": {
                                  "type": "number"
                                }
                              },
                              "required": [
                                "employeeContribution",
                                "employerContribution",
                                "taxRelief",
                                "sacrificeAmount"
                              ]
                            },
                            "salarySacrifice": {
                              "type": "object",
                              "properties": {
                                "schemes": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "scheme": {
                                        "type": "string",
                                        "enum": [
                                          "cycle_to_work",
                                          "holiday_buy",
                                          "ev_car",
                                          "pension_increase"
                                        ]
                                      },
                                      "amount": {
                                        "type": "number"
                                      },
                                      "displayName": {
                                        "type": "string"
                                      },
                                      "days": {
                                        "type": "number"
                                      },
                                      "monthlyAmount": {
                                        "type": "number"
                                      },
                                      "leaseMonths": {
                                        "type": "number"
                                      },
                                      "p11dValue": {
                                        "type": "number"
                                      }
                                    },
                                    "required": [
                                      "scheme",
                                      "amount",
                                      "displayName"
                                    ]
                                  }
                                },
                                "totalSacrifice": {
                                  "type": "number"
                                },
                                "adjustedGross": {
                                  "type": "number"
                                },
                                "taxSaving": {
                                  "type": "number"
                                },
                                "niSaving": {
                                  "type": "number"
                                },
                                "benefitInKindTax": {
                                  "type": "number"
                                },
                                "effectiveSaving": {
                                  "type": "number"
                                },
                                "netCostToEmployee": {
                                  "type": "number"
                                },
                                "takeHomeChange": {
                                  "type": "number"
                                },
                                "warnings": {
                                  "type": "array",
                                  "items": {
                                    "type": "string"
                                  }
                                }
                              },
                              "required": [
                                "schemes",
                                "totalSacrifice",
                                "adjustedGross",
                                "taxSaving",
                                "niSaving",
                                "benefitInKindTax",
                                "effectiveSaving",
                                "netCostToEmployee",
                                "takeHomeChange",
                                "warnings"
                              ]
                            },
                            "childBenefit": {
                              "type": "object",
                              "properties": {
                                "weeklyBenefit": {
                                  "type": "number"
                                },
                                "annualBenefit": {
                                  "type": "number"
                                },
                                "hiChargeRate": {
                                  "type": "number"
                                },
                                "hiChargeAmount": {
                                  "type": "number"
                                },
                                "netBenefit": {
                                  "type": "number"
                                }
                              },
                              "required": [
                                "weeklyBenefit",
                                "annualBenefit",
                                "hiChargeRate",
                                "hiChargeAmount",
                                "netBenefit"
                              ]
                            },
                            "marriageAllowance": {
                              "type": "object",
                              "properties": {
                                "transferred": {
                                  "type": "number"
                                },
                                "taxSaving": {
                                  "type": "number"
                                }
                              },
                              "required": [
                                "transferred",
                                "taxSaving"
                              ]
                            },
                            "totalDeductions": {
                              "type": "number"
                            },
                            "netAnnual": {
                              "type": "number"
                            },
                            "breakdown": {
                              "type": "object",
                              "properties": {
                                "yearly": {
                                  "type": "object",
                                  "properties": {
                                    "gross": {
                                      "type": "number"
                                    },
                                    "salarySacrifice": {
                                      "type": "number"
                                    },
                                    "taxablePay": {
                                      "type": "number"
                                    },
                                    "incomeTax": {
                                      "type": "number"
                                    },
                                    "benefitInKindTax": {
                                      "type": "number"
                                    },
                                    "nationalInsurance": {
                                      "type": "number"
                                    },
                                    "studentLoan": {
                                      "type": "number"
                                    },
                                    "pension": {
                                      "type": "number"
                                    },
                                    "totalDeductions": {
                                      "type": "number"
                                    },
                                    "net": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "gross",
                                    "salarySacrifice",
                                    "taxablePay",
                                    "incomeTax",
                                    "benefitInKindTax",
                                    "nationalInsurance",
                                    "studentLoan",
                                    "pension",
                                    "totalDeductions",
                                    "net"
                                  ]
                                },
                                "monthly": {
                                  "type": "object",
                                  "properties": {
                                    "gross": {
                                      "type": "number"
                                    },
                                    "salarySacrifice": {
                                      "type": "number"
                                    },
                                    "taxablePay": {
                                      "type": "number"
                                    },
                                    "incomeTax": {
                                      "type": "number"
                                    },
                                    "benefitInKindTax": {
                                      "type": "number"
                                    },
                                    "nationalInsurance": {
                                      "type": "number"
                                    },
                                    "studentLoan": {
                                      "type": "number"
                                    },
                                    "pension": {
                                      "type": "number"
                                    },
                                    "totalDeductions": {
                                      "type": "number"
                                    },
                                    "net": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "gross",
                                    "salarySacrifice",
                                    "taxablePay",
                                    "incomeTax",
                                    "benefitInKindTax",
                                    "nationalInsurance",
                                    "studentLoan",
                                    "pension",
                                    "totalDeductions",
                                    "net"
                                  ]
                                },
                                "fourWeekly": {
                                  "type": "object",
                                  "properties": {
                                    "gross": {
                                      "type": "number"
                                    },
                                    "salarySacrifice": {
                                      "type": "number"
                                    },
                                    "taxablePay": {
                                      "type": "number"
                                    },
                                    "incomeTax": {
                                      "type": "number"
                                    },
                                    "benefitInKindTax": {
                                      "type": "number"
                                    },
                                    "nationalInsurance": {
                                      "type": "number"
                                    },
                                    "studentLoan": {
                                      "type": "number"
                                    },
                                    "pension": {
                                      "type": "number"
                                    },
                                    "totalDeductions": {
                                      "type": "number"
                                    },
                                    "net": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "gross",
                                    "salarySacrifice",
                                    "taxablePay",
                                    "incomeTax",
                                    "benefitInKindTax",
                                    "nationalInsurance",
                                    "studentLoan",
                                    "pension",
                                    "totalDeductions",
                                    "net"
                                  ]
                                },
                                "twoWeekly": {
                                  "type": "object",
                                  "properties": {
                                    "gross": {
                                      "type": "number"
                                    },
                                    "salarySacrifice": {
                                      "type": "number"
                                    },
                                    "taxablePay": {
                                      "type": "number"
                                    },
                                    "incomeTax": {
                                      "type": "number"
                                    },
                                    "benefitInKindTax": {
                                      "type": "number"
                                    },
                                    "nationalInsurance": {
                                      "type": "number"
                                    },
                                    "studentLoan": {
                                      "type": "number"
                                    },
                                    "pension": {
                                      "type": "number"
                                    },
                                    "totalDeductions": {
                                      "type": "number"
                                    },
                                    "net": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "gross",
                                    "salarySacrifice",
                                    "taxablePay",
                                    "incomeTax",
                                    "benefitInKindTax",
                                    "nationalInsurance",
                                    "studentLoan",
                                    "pension",
                                    "totalDeductions",
                                    "net"
                                  ]
                                },
                                "weekly": {
                                  "type": "object",
                                  "properties": {
                                    "gross": {
                                      "type": "number"
                                    },
                                    "salarySacrifice": {
                                      "type": "number"
                                    },
                                    "taxablePay": {
                                      "type": "number"
                                    },
                                    "incomeTax": {
                                      "type": "number"
                                    },
                                    "benefitInKindTax": {
                                      "type": "number"
                                    },
                                    "nationalInsurance": {
                                      "type": "number"
                                    },
                                    "studentLoan": {
                                      "type": "number"
                                    },
                                    "pension": {
                                      "type": "number"
                                    },
                                    "totalDeductions": {
                                      "type": "number"
                                    },
                                    "net": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "gross",
                                    "salarySacrifice",
                                    "taxablePay",
                                    "incomeTax",
                                    "benefitInKindTax",
                                    "nationalInsurance",
                                    "studentLoan",
                                    "pension",
                                    "totalDeductions",
                                    "net"
                                  ]
                                },
                                "daily": {
                                  "type": "object",
                                  "properties": {
                                    "gross": {
                                      "type": "number"
                                    },
                                    "salarySacrifice": {
                                      "type": "number"
                                    },
                                    "taxablePay": {
                                      "type": "number"
                                    },
                                    "incomeTax": {
                                      "type": "number"
                                    },
                                    "benefitInKindTax": {
                                      "type": "number"
                                    },
                                    "nationalInsurance": {
                                      "type": "number"
                                    },
                                    "studentLoan": {
                                      "type": "number"
                                    },
                                    "pension": {
                                      "type": "number"
                                    },
                                    "totalDeductions": {
                                      "type": "number"
                                    },
                                    "net": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "gross",
                                    "salarySacrifice",
                                    "taxablePay",
                                    "incomeTax",
                                    "benefitInKindTax",
                                    "nationalInsurance",
                                    "studentLoan",
                                    "pension",
                                    "totalDeductions",
                                    "net"
                                  ]
                                },
                                "hourly": {
                                  "type": "object",
                                  "properties": {
                                    "gross": {
                                      "type": "number"
                                    },
                                    "salarySacrifice": {
                                      "type": "number"
                                    },
                                    "taxablePay": {
                                      "type": "number"
                                    },
                                    "incomeTax": {
                                      "type": "number"
                                    },
                                    "benefitInKindTax": {
                                      "type": "number"
                                    },
                                    "nationalInsurance": {
                                      "type": "number"
                                    },
                                    "studentLoan": {
                                      "type": "number"
                                    },
                                    "pension": {
                                      "type": "number"
                                    },
                                    "totalDeductions": {
                                      "type": "number"
                                    },
                                    "net": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "gross",
                                    "salarySacrifice",
                                    "taxablePay",
                                    "incomeTax",
                                    "benefitInKindTax",
                                    "nationalInsurance",
                                    "studentLoan",
                                    "pension",
                                    "totalDeductions",
                                    "net"
                                  ]
                                }
                              },
                              "required": [
                                "yearly",
                                "monthly",
                                "fourWeekly",
                                "twoWeekly",
                                "weekly",
                                "daily",
                                "hourly"
                              ]
                            },
                            "effectiveTaxRate": {
                              "type": "number"
                            },
                            "marginalTaxRate": {
                              "type": "number"
                            },
                            "previousYear": {
                              "type": "object",
                              "properties": {
                                "netAnnual": {
                                  "type": "number"
                                },
                                "difference": {
                                  "type": "number"
                                },
                                "differenceMonthly": {
                                  "type": "number"
                                }
                              },
                              "required": [
                                "netAnnual",
                                "difference",
                                "differenceMonthly"
                              ]
                            }
                          },
                          "required": [
                            "inputs",
                            "grossAnnual",
                            "personalAllowance",
                            "taxableIncome",
                            "incomeTax",
                            "nationalInsurance",
                            "studentLoans",
                            "pension",
                            "salarySacrifice",
                            "totalDeductions",
                            "netAnnual",
                            "breakdown",
                            "effectiveTaxRate",
                            "marginalTaxRate"
                          ]
                        },
                        "secondary": {
                          "type": "object",
                          "properties": {
                            "inputs": {
                              "type": "object",
                              "properties": {
                                "taxYear": {
                                  "type": "string"
                                },
                                "region": {
                                  "type": "string",
                                  "enum": [
                                    "england",
                                    "wales",
                                    "scotland",
                                    "northern-ireland"
                                  ]
                                },
                                "salary": {
                                  "type": "number"
                                },
                                "frequency": {
                                  "type": "string",
                                  "enum": [
                                    "year",
                                    "month",
                                    "fourWeeks",
                                    "twoWeeks",
                                    "week",
                                    "day",
                                    "hour"
                                  ]
                                },
                                "taxCode": {
                                  "type": "string"
                                },
                                "studentLoans": {
                                  "type": "array",
                                  "items": {
                                    "type": "string"
                                  }
                                },
                                "pension": {
                                  "type": "object",
                                  "properties": {
                                    "type": {
                                      "type": "string",
                                      "enum": [
                                        "percent",
                                        "fixed"
                                      ]
                                    },
                                    "value": {
                                      "type": "number"
                                    },
                                    "relief": {
                                      "type": "string",
                                      "enum": [
                                        "net",
                                        "gross",
                                        "net_pay"
                                      ]
                                    }
                                  },
                                  "required": [
                                    "type",
                                    "value",
                                    "relief"
                                  ]
                                },
                                "personalPension": {
                                  "type": "object",
                                  "properties": {
                                    "type": {
                                      "type": "string",
                                      "enum": [
                                        "percent",
                                        "fixed"
                                      ]
                                    },
                                    "value": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "type",
                                    "value"
                                  ]
                                },
                                "childrenCount": {
                                  "type": "number"
                                },
                                "married": {
                                  "type": "boolean"
                                },
                                "partnerIncome": {
                                  "type": "number"
                                },
                                "blind": {
                                  "type": "boolean"
                                },
                                "noNI": {
                                  "type": "boolean"
                                },
                                "age": {
                                  "type": "string",
                                  "enum": [
                                    "under65",
                                    "65to74",
                                    "over75"
                                  ]
                                },
                                "overtime": {
                                  "type": "object",
                                  "properties": {
                                    "hours": {
                                      "type": "number"
                                    },
                                    "rate": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "hours",
                                    "rate"
                                  ]
                                },
                                "bonus": {
                                  "type": "number"
                                },
                                "additionalAllowances": {
                                  "type": "number"
                                },
                                "hoursPerWeek": {
                                  "type": "number"
                                },
                                "salarySacrifice": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "scheme": {
                                        "type": "string",
                                        "enum": [
                                          "cycle_to_work",
                                          "holiday_buy",
                                          "ev_car",
                                          "pension_increase"
                                        ]
                                      },
                                      "amount": {
                                        "type": "number"
                                      },
                                      "days": {
                                        "type": "number"
                                      },
                                      "monthlyAmount": {
                                        "type": "number"
                                      },
                                      "leaseMonths": {
                                        "type": "number"
                                      },
                                      "p11dValue": {
                                        "type": "number"
                                      }
                                    },
                                    "required": [
                                      "scheme",
                                      "amount"
                                    ]
                                  }
                                }
                              },
                              "required": [
                                "taxYear",
                                "region",
                                "salary",
                                "frequency"
                              ]
                            },
                            "grossAnnual": {
                              "type": "number"
                            },
                            "personalAllowance": {
                              "type": "number"
                            },
                            "taxableIncome": {
                              "type": "number"
                            },
                            "incomeTax": {
                              "type": "object",
                              "properties": {
                                "taxableIncome": {
                                  "type": "number"
                                },
                                "personalAllowance": {
                                  "type": "number"
                                },
                                "bands": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "name": {
                                        "type": "string"
                                      },
                                      "rate": {
                                        "type": "number"
                                      },
                                      "taxable": {
                                        "type": "number"
                                      },
                                      "tax": {
                                        "type": "number"
                                      }
                                    },
                                    "required": [
                                      "name",
                                      "rate",
                                      "taxable",
                                      "tax"
                                    ]
                                  }
                                },
                                "totalTax": {
                                  "type": "number"
                                },
                                "effectiveRate": {
                                  "type": "number"
                                },
                                "marginalRate": {
                                  "type": "number"
                                }
                              },
                              "required": [
                                "taxableIncome",
                                "personalAllowance",
                                "bands",
                                "totalTax",
                                "effectiveRate",
                                "marginalRate"
                              ]
                            },
                            "nationalInsurance": {
                              "type": "object",
                              "properties": {
                                "employee": {
                                  "type": "object",
                                  "properties": {
                                    "earnings": {
                                      "type": "number"
                                    },
                                    "mainContribution": {
                                      "type": "number"
                                    },
                                    "upperContribution": {
                                      "type": "number"
                                    },
                                    "totalContribution": {
                                      "type": "number"
                                    },
                                    "effectiveRate": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "earnings",
                                    "mainContribution",
                                    "upperContribution",
                                    "totalContribution",
                                    "effectiveRate"
                                  ]
                                },
                                "employer": {
                                  "type": "object",
                                  "properties": {
                                    "earnings": {
                                      "type": "number"
                                    },
                                    "contribution": {
                                      "type": "number"
                                    },
                                    "effectiveRate": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "earnings",
                                    "contribution",
                                    "effectiveRate"
                                  ]
                                }
                              },
                              "required": [
                                "employee",
                                "employer"
                              ]
                            },
                            "studentLoans": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "plan": {
                                    "type": "string"
                                  },
                                  "threshold": {
                                    "type": "number"
                                  },
                                  "rate": {
                                    "type": "number"
                                  },
                                  "repayment": {
                                    "type": "number"
                                  }
                                },
                                "required": [
                                  "plan",
                                  "threshold",
                                  "rate",
                                  "repayment"
                                ]
                              }
                            },
                            "pension": {
                              "type": "object",
                              "properties": {
                                "employeeContribution": {
                                  "type": "number"
                                },
                                "employerContribution": {
                                  "type": "number"
                                },
                                "taxRelief": {
                                  "type": "number"
                                },
                                "sacrificeAmount": {
                                  "type": "number"
                                }
                              },
                              "required": [
                                "employeeContribution",
                                "employerContribution",
                                "taxRelief",
                                "sacrificeAmount"
                              ]
                            },
                            "salarySacrifice": {
                              "type": "object",
                              "properties": {
                                "schemes": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "scheme": {
                                        "type": "string",
                                        "enum": [
                                          "cycle_to_work",
                                          "holiday_buy",
                                          "ev_car",
                                          "pension_increase"
                                        ]
                                      },
                                      "amount": {
                                        "type": "number"
                                      },
                                      "displayName": {
                                        "type": "string"
                                      },
                                      "days": {
                                        "type": "number"
                                      },
                                      "monthlyAmount": {
                                        "type": "number"
                                      },
                                      "leaseMonths": {
                                        "type": "number"
                                      },
                                      "p11dValue": {
                                        "type": "number"
                                      }
                                    },
                                    "required": [
                                      "scheme",
                                      "amount",
                                      "displayName"
                                    ]
                                  }
                                },
                                "totalSacrifice": {
                                  "type": "number"
                                },
                                "adjustedGross": {
                                  "type": "number"
                                },
                                "taxSaving": {
                                  "type": "number"
                                },
                                "niSaving": {
                                  "type": "number"
                                },
                                "benefitInKindTax": {
                                  "type": "number"
                                },
                                "effectiveSaving": {
                                  "type": "number"
                                },
                                "netCostToEmployee": {
                                  "type": "number"
                                },
                                "takeHomeChange": {
                                  "type": "number"
                                },
                                "warnings": {
                                  "type": "array",
                                  "items": {
                                    "type": "string"
                                  }
                                }
                              },
                              "required": [
                                "schemes",
                                "totalSacrifice",
                                "adjustedGross",
                                "taxSaving",
                                "niSaving",
                                "benefitInKindTax",
                                "effectiveSaving",
                                "netCostToEmployee",
                                "takeHomeChange",
                                "warnings"
                              ]
                            },
                            "childBenefit": {
                              "type": "object",
                              "properties": {
                                "weeklyBenefit": {
                                  "type": "number"
                                },
                                "annualBenefit": {
                                  "type": "number"
                                },
                                "hiChargeRate": {
                                  "type": "number"
                                },
                                "hiChargeAmount": {
                                  "type": "number"
                                },
                                "netBenefit": {
                                  "type": "number"
                                }
                              },
                              "required": [
                                "weeklyBenefit",
                                "annualBenefit",
                                "hiChargeRate",
                                "hiChargeAmount",
                                "netBenefit"
                              ]
                            },
                            "marriageAllowance": {
                              "type": "object",
                              "properties": {
                                "transferred": {
                                  "type": "number"
                                },
                                "taxSaving": {
                                  "type": "number"
                                }
                              },
                              "required": [
                                "transferred",
                                "taxSaving"
                              ]
                            },
                            "totalDeductions": {
                              "type": "number"
                            },
                            "netAnnual": {
                              "type": "number"
                            },
                            "breakdown": {
                              "type": "object",
                              "properties": {
                                "yearly": {
                                  "type": "object",
                                  "properties": {
                                    "gross": {
                                      "type": "number"
                                    },
                                    "salarySacrifice": {
                                      "type": "number"
                                    },
                                    "taxablePay": {
                                      "type": "number"
                                    },
                                    "incomeTax": {
                                      "type": "number"
                                    },
                                    "benefitInKindTax": {
                                      "type": "number"
                                    },
                                    "nationalInsurance": {
                                      "type": "number"
                                    },
                                    "studentLoan": {
                                      "type": "number"
                                    },
                                    "pension": {
                                      "type": "number"
                                    },
                                    "totalDeductions": {
                                      "type": "number"
                                    },
                                    "net": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "gross",
                                    "salarySacrifice",
                                    "taxablePay",
                                    "incomeTax",
                                    "benefitInKindTax",
                                    "nationalInsurance",
                                    "studentLoan",
                                    "pension",
                                    "totalDeductions",
                                    "net"
                                  ]
                                },
                                "monthly": {
                                  "type": "object",
                                  "properties": {
                                    "gross": {
                                      "type": "number"
                                    },
                                    "salarySacrifice": {
                                      "type": "number"
                                    },
                                    "taxablePay": {
                                      "type": "number"
                                    },
                                    "incomeTax": {
                                      "type": "number"
                                    },
                                    "benefitInKindTax": {
                                      "type": "number"
                                    },
                                    "nationalInsurance": {
                                      "type": "number"
                                    },
                                    "studentLoan": {
                                      "type": "number"
                                    },
                                    "pension": {
                                      "type": "number"
                                    },
                                    "totalDeductions": {
                                      "type": "number"
                                    },
                                    "net": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "gross",
                                    "salarySacrifice",
                                    "taxablePay",
                                    "incomeTax",
                                    "benefitInKindTax",
                                    "nationalInsurance",
                                    "studentLoan",
                                    "pension",
                                    "totalDeductions",
                                    "net"
                                  ]
                                },
                                "fourWeekly": {
                                  "type": "object",
                                  "properties": {
                                    "gross": {
                                      "type": "number"
                                    },
                                    "salarySacrifice": {
                                      "type": "number"
                                    },
                                    "taxablePay": {
                                      "type": "number"
                                    },
                                    "incomeTax": {
                                      "type": "number"
                                    },
                                    "benefitInKindTax": {
                                      "type": "number"
                                    },
                                    "nationalInsurance": {
                                      "type": "number"
                                    },
                                    "studentLoan": {
                                      "type": "number"
                                    },
                                    "pension": {
                                      "type": "number"
                                    },
                                    "totalDeductions": {
                                      "type": "number"
                                    },
                                    "net": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "gross",
                                    "salarySacrifice",
                                    "taxablePay",
                                    "incomeTax",
                                    "benefitInKindTax",
                                    "nationalInsurance",
                                    "studentLoan",
                                    "pension",
                                    "totalDeductions",
                                    "net"
                                  ]
                                },
                                "twoWeekly": {
                                  "type": "object",
                                  "properties": {
                                    "gross": {
                                      "type": "number"
                                    },
                                    "salarySacrifice": {
                                      "type": "number"
                                    },
                                    "taxablePay": {
                                      "type": "number"
                                    },
                                    "incomeTax": {
                                      "type": "number"
                                    },
                                    "benefitInKindTax": {
                                      "type": "number"
                                    },
                                    "nationalInsurance": {
                                      "type": "number"
                                    },
                                    "studentLoan": {
                                      "type": "number"
                                    },
                                    "pension": {
                                      "type": "number"
                                    },
                                    "totalDeductions": {
                                      "type": "number"
                                    },
                                    "net": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "gross",
                                    "salarySacrifice",
                                    "taxablePay",
                                    "incomeTax",
                                    "benefitInKindTax",
                                    "nationalInsurance",
                                    "studentLoan",
                                    "pension",
                                    "totalDeductions",
                                    "net"
                                  ]
                                },
                                "weekly": {
                                  "type": "object",
                                  "properties": {
                                    "gross": {
                                      "type": "number"
                                    },
                                    "salarySacrifice": {
                                      "type": "number"
                                    },
                                    "taxablePay": {
                                      "type": "number"
                                    },
                                    "incomeTax": {
                                      "type": "number"
                                    },
                                    "benefitInKindTax": {
                                      "type": "number"
                                    },
                                    "nationalInsurance": {
                                      "type": "number"
                                    },
                                    "studentLoan": {
                                      "type": "number"
                                    },
                                    "pension": {
                                      "type": "number"
                                    },
                                    "totalDeductions": {
                                      "type": "number"
                                    },
                                    "net": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "gross",
                                    "salarySacrifice",
                                    "taxablePay",
                                    "incomeTax",
                                    "benefitInKindTax",
                                    "nationalInsurance",
                                    "studentLoan",
                                    "pension",
                                    "totalDeductions",
                                    "net"
                                  ]
                                },
                                "daily": {
                                  "type": "object",
                                  "properties": {
                                    "gross": {
                                      "type": "number"
                                    },
                                    "salarySacrifice": {
                                      "type": "number"
                                    },
                                    "taxablePay": {
                                      "type": "number"
                                    },
                                    "incomeTax": {
                                      "type": "number"
                                    },
                                    "benefitInKindTax": {
                                      "type": "number"
                                    },
                                    "nationalInsurance": {
                                      "type": "number"
                                    },
                                    "studentLoan": {
                                      "type": "number"
                                    },
                                    "pension": {
                                      "type": "number"
                                    },
                                    "totalDeductions": {
                                      "type": "number"
                                    },
                                    "net": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "gross",
                                    "salarySacrifice",
                                    "taxablePay",
                                    "incomeTax",
                                    "benefitInKindTax",
                                    "nationalInsurance",
                                    "studentLoan",
                                    "pension",
                                    "totalDeductions",
                                    "net"
                                  ]
                                },
                                "hourly": {
                                  "type": "object",
                                  "properties": {
                                    "gross": {
                                      "type": "number"
                                    },
                                    "salarySacrifice": {
                                      "type": "number"
                                    },
                                    "taxablePay": {
                                      "type": "number"
                                    },
                                    "incomeTax": {
                                      "type": "number"
                                    },
                                    "benefitInKindTax": {
                                      "type": "number"
                                    },
                                    "nationalInsurance": {
                                      "type": "number"
                                    },
                                    "studentLoan": {
                                      "type": "number"
                                    },
                                    "pension": {
                                      "type": "number"
                                    },
                                    "totalDeductions": {
                                      "type": "number"
                                    },
                                    "net": {
                                      "type": "number"
                                    }
                                  },
                                  "required": [
                                    "gross",
                                    "salarySacrifice",
                                    "taxablePay",
                                    "incomeTax",
                                    "benefitInKindTax",
                                    "nationalInsurance",
                                    "studentLoan",
                                    "pension",
                                    "totalDeductions",
                                    "net"
                                  ]
                                }
                              },
                              "required": [
                                "yearly",
                                "monthly",
                                "fourWeekly",
                                "twoWeekly",
                                "weekly",
                                "daily",
                                "hourly"
                              ]
                            },
                            "effectiveTaxRate": {
                              "type": "number"
                            },
                            "marginalTaxRate": {
                              "type": "number"
                            },
                            "previousYear": {
                              "type": "object",
                              "properties": {
                                "netAnnual": {
                                  "type": "number"
                                },
                                "difference": {
                                  "type": "number"
                                },
                                "differenceMonthly": {
                                  "type": "number"
                                }
                              },
                              "required": [
                                "netAnnual",
                                "difference",
                                "differenceMonthly"
                              ]
                            }
                          },
                          "required": [
                            "inputs",
                            "grossAnnual",
                            "personalAllowance",
                            "taxableIncome",
                            "incomeTax",
                            "nationalInsurance",
                            "studentLoans",
                            "pension",
                            "salarySacrifice",
                            "totalDeductions",
                            "netAnnual",
                            "breakdown",
                            "effectiveTaxRate",
                            "marginalTaxRate"
                          ]
                        },
                        "combined": {
                          "type": "object",
                          "properties": {
                            "grossAnnual": {
                              "type": "number"
                            },
                            "totalIncomeTax": {
                              "type": "number"
                            },
                            "totalNI": {
                              "type": "number"
                            },
                            "totalStudentLoan": {
                              "type": "number"
                            },
                            "totalPension": {
                              "type": "number"
                            },
                            "totalDeductions": {
                              "type": "number"
                            },
                            "netAnnual": {
                              "type": "number"
                            },
                            "effectiveTaxRate": {
                              "type": "number"
                            }
                          },
                          "required": [
                            "grossAnnual",
                            "totalIncomeTax",
                            "totalNI",
                            "totalStudentLoan",
                            "totalPension",
                            "totalDeductions",
                            "netAnnual",
                            "effectiveTaxRate"
                          ]
                        },
                        "niOverpayment": {
                          "type": "object",
                          "properties": {
                            "combinedNI": {
                              "type": "number"
                            },
                            "annualMaximumNI": {
                              "type": "number"
                            },
                            "estimatedOverpayment": {
                              "type": "number"
                            },
                            "refundNote": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "combinedNI",
                            "annualMaximumNI",
                            "estimatedOverpayment",
                            "refundNote"
                          ]
                        },
                        "warnings": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      },
                      "required": [
                        "primary",
                        "secondary",
                        "combined",
                        "niOverpayment",
                        "warnings"
                      ]
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "version": {
                          "type": "string"
                        },
                        "taxYear": {
                          "type": "string"
                        },
                        "calculatedAt": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "version",
                        "taxYear",
                        "calculatedAt"
                      ]
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Validation error (VALIDATION_ERROR) or malformed JSON (INVALID_JSON)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "API key is invalid, disabled, or expired (INVALID_KEY)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded (RATE_LIMITED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Auth or rate limiting not configured (AUTH_UNAVAILABLE, SERVICE_UNAVAILABLE)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/statutory-pay": {
      "post": {
        "summary": "Statutory pay calculator",
        "description": "Estimates SMP, SSP or SPP using salary/52. Checks earnings only, not full eligibility. Assumes weekly NI and selected-year rates throughout; net amounts exclude pensions; selected student loans use weekly PAYE thresholds. monthlyBreakdown contains four-week blocks.",
        "operationId": "statutoryPay",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "payType": {
                    "type": "string",
                    "enum": [
                      "smp",
                      "ssp",
                      "spp"
                    ]
                  },
                  "salary": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 1000000000
                  },
                  "taxYear": {
                    "type": "string",
                    "enum": [
                      "2024-25",
                      "2025-26",
                      "2026-27"
                    ]
                  },
                  "region": {
                    "type": "string",
                    "enum": [
                      "england",
                      "wales",
                      "scotland",
                      "northern-ireland"
                    ]
                  },
                  "taxCode": {
                    "type": "string",
                    "maxLength": 20
                  },
                  "studentLoans": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "plan1",
                        "plan2",
                        "plan4",
                        "plan5",
                        "postgraduate"
                      ]
                    },
                    "maxItems": 10
                  },
                  "enhancedWeeks": {
                    "type": "integer",
                    "minimum": 0
                  },
                  "enhancedRate": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 1
                  },
                  "daysPerWeek": {
                    "type": "number",
                    "exclusiveMinimum": 0
                  },
                  "weeksRequested": {
                    "type": "integer",
                    "exclusiveMinimum": 0
                  }
                },
                "required": [
                  "payType",
                  "salary",
                  "taxYear",
                  "region"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful calculation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "payType": {
                          "type": "string",
                          "enum": [
                            "smp",
                            "ssp",
                            "spp"
                          ]
                        },
                        "payTypeLabel": {
                          "type": "string"
                        },
                        "averageWeeklyEarnings": {
                          "type": "number"
                        },
                        "qualifies": {
                          "type": "boolean",
                          "description": "Earnings test only, not confirmation of employment or notice eligibility"
                        },
                        "qualificationNote": {
                          "type": "string"
                        },
                        "schedule": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "weekNumber": {
                                "type": "number"
                              },
                              "grossPay": {
                                "type": "number"
                              },
                              "payType": {
                                "type": "string"
                              },
                              "estimatedTax": {
                                "type": "number"
                              },
                              "estimatedNI": {
                                "type": "number"
                              },
                              "estimatedStudentLoan": {
                                "type": "number"
                              },
                              "estimatedNet": {
                                "type": "number"
                              }
                            },
                            "required": [
                              "weekNumber",
                              "grossPay",
                              "payType",
                              "estimatedTax",
                              "estimatedNI",
                              "estimatedNet"
                            ]
                          }
                        },
                        "summary": {
                          "type": "object",
                          "properties": {
                            "totalWeeks": {
                              "type": "number"
                            },
                            "totalGross": {
                              "type": "number"
                            },
                            "totalTax": {
                              "type": "number"
                            },
                            "totalNI": {
                              "type": "number"
                            },
                            "totalStudentLoan": {
                              "type": "number"
                            },
                            "totalNet": {
                              "type": "number"
                            }
                          },
                          "required": [
                            "totalWeeks",
                            "totalGross",
                            "totalTax",
                            "totalNI",
                            "totalNet"
                          ]
                        },
                        "normalSalaryComparison": {
                          "type": "object",
                          "properties": {
                            "normalNetForPeriod": {
                              "type": "number"
                            },
                            "netLoss": {
                              "type": "number"
                            },
                            "netLossPercent": {
                              "type": "number"
                            }
                          },
                          "required": [
                            "normalNetForPeriod",
                            "netLoss",
                            "netLossPercent"
                          ]
                        },
                        "monthlyBreakdown": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "month": {
                                "type": "number"
                              },
                              "grossPay": {
                                "type": "number"
                              },
                              "netPay": {
                                "type": "number"
                              }
                            },
                            "required": [
                              "month",
                              "grossPay",
                              "netPay"
                            ]
                          }
                        }
                      },
                      "required": [
                        "payType",
                        "payTypeLabel",
                        "averageWeeklyEarnings",
                        "qualifies",
                        "qualificationNote",
                        "schedule",
                        "summary",
                        "normalSalaryComparison",
                        "monthlyBreakdown"
                      ]
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "version": {
                          "type": "string"
                        },
                        "taxYear": {
                          "type": "string"
                        },
                        "calculatedAt": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "version",
                        "taxYear",
                        "calculatedAt"
                      ]
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Validation error (VALIDATION_ERROR) or malformed JSON (INVALID_JSON)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "API key is invalid, disabled, or expired (INVALID_KEY)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded (RATE_LIMITED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Auth or rate limiting not configured (AUTH_UNAVAILABLE, SERVICE_UNAVAILABLE)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/mortgage": {
      "post": {
        "summary": "Mortgage affordability calculator",
        "description": "Estimates borrowing range, repayments, stress test, and affordability verdict.",
        "operationId": "mortgageAffordability",
        "security": [
          {
            "BearerAuth": []
          },
          {}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "grossSalary": {
                    "type": "number",
                    "exclusiveMinimum": 0,
                    "maximum": 1000000000
                  },
                  "jointGrossSalary": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 1000000000
                  },
                  "region": {
                    "type": "string",
                    "enum": [
                      "england",
                      "wales",
                      "scotland",
                      "northern-ireland"
                    ]
                  },
                  "deposit": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 1000000000
                  },
                  "propertyValue": {
                    "type": "number",
                    "exclusiveMinimum": 0,
                    "maximum": 1000000000
                  },
                  "existingMonthlyDebts": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 1000000000
                  },
                  "termYears": {
                    "type": "integer",
                    "exclusiveMinimum": 0,
                    "maximum": 100
                  },
                  "taxYear": {
                    "type": "string",
                    "enum": [
                      "2024-25",
                      "2025-26",
                      "2026-27"
                    ]
                  }
                },
                "required": [
                  "grossSalary",
                  "region",
                  "deposit"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful calculation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "totalGrossIncome": {
                          "type": "number"
                        },
                        "borrowingRange": {
                          "type": "object",
                          "properties": {
                            "comfortable": {
                              "type": "number"
                            },
                            "stretched": {
                              "type": "number"
                            },
                            "maximum": {
                              "type": "number"
                            },
                            "incomeMultipleCap": {
                              "type": "number",
                              "description": "This model’s illustrative 4.5x gross income cap; a tier equal to this is capped by income, not DTI"
                            }
                          },
                          "required": [
                            "comfortable",
                            "stretched",
                            "maximum",
                            "incomeMultipleCap"
                          ]
                        },
                        "ltvAnalysis": {
                          "type": [
                            "object",
                            "null"
                          ],
                          "properties": {
                            "ltv": {
                              "type": "number"
                            },
                            "ltvPercent": {
                              "type": "number"
                            },
                            "tier": {
                              "type": "string"
                            },
                            "tierLabel": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "ltv",
                            "ltvPercent",
                            "tier",
                            "tierLabel"
                          ]
                        },
                        "monthlyRepayments": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "rate": {
                                "type": "number"
                              },
                              "rateLabel": {
                                "type": "string"
                              },
                              "monthly": {
                                "type": "number"
                              },
                              "totalCost": {
                                "type": "number"
                              },
                              "totalInterest": {
                                "type": "number"
                              }
                            },
                            "required": [
                              "rate",
                              "rateLabel",
                              "monthly",
                              "totalCost",
                              "totalInterest"
                            ]
                          }
                        },
                        "stressTest": {
                          "type": "object",
                          "properties": {
                            "stressRate": {
                              "type": "number"
                            },
                            "monthlyAtStress": {
                              "type": "number"
                            },
                            "affordable": {
                              "type": "boolean"
                            }
                          },
                          "required": [
                            "stressRate",
                            "monthlyAtStress",
                            "affordable"
                          ]
                        },
                        "affordability": {
                          "type": "object",
                          "properties": {
                            "netMonthly": {
                              "type": "number"
                            },
                            "monthlyCommitments": {
                              "type": "number"
                            },
                            "proposedMortgagePayment": {
                              "type": "number"
                            },
                            "availableForMortgage": {
                              "type": "number"
                            },
                            "dtiRatio": {
                              "type": "number"
                            },
                            "dtiVerdict": {
                              "type": "string",
                              "enum": [
                                "comfortable",
                                "stretched",
                                "unlikely"
                              ]
                            }
                          },
                          "required": [
                            "netMonthly",
                            "monthlyCommitments",
                            "proposedMortgagePayment",
                            "availableForMortgage",
                            "dtiRatio",
                            "dtiVerdict"
                          ]
                        },
                        "targetVerdict": {
                          "type": [
                            "object",
                            "null"
                          ],
                          "properties": {
                            "targetLoanAmount": {
                              "type": "number"
                            },
                            "targetMonthlyPayment": {
                              "type": "number"
                            },
                            "targetDtiRatio": {
                              "type": "number"
                            },
                            "targetDtiVerdict": {
                              "type": "string",
                              "enum": [
                                "comfortable",
                                "stretched",
                                "unlikely"
                              ]
                            },
                            "targetStressPayment": {
                              "type": "number"
                            },
                            "targetStressAffordable": {
                              "type": "boolean"
                            },
                            "exceedsIncomeMultipleCap": {
                              "type": "boolean"
                            },
                            "verdict": {
                              "type": "string",
                              "enum": [
                                "comfortable",
                                "stretched",
                                "unlikely"
                              ],
                              "description": "Overall verdict: 'unlikely' when above the income cap, else the DTI verdict"
                            }
                          },
                          "required": [
                            "targetLoanAmount",
                            "targetMonthlyPayment",
                            "targetDtiRatio",
                            "targetDtiVerdict",
                            "targetStressPayment",
                            "targetStressAffordable",
                            "exceedsIncomeMultipleCap",
                            "verdict"
                          ]
                        },
                        "termYears": {
                          "type": "number"
                        },
                        "loanAmount": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "totalGrossIncome",
                        "borrowingRange",
                        "ltvAnalysis",
                        "monthlyRepayments",
                        "stressTest",
                        "affordability",
                        "targetVerdict",
                        "termYears",
                        "loanAmount"
                      ]
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "version": {
                          "type": "string"
                        },
                        "taxYear": {
                          "type": "string"
                        },
                        "calculatedAt": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "version",
                        "taxYear",
                        "calculatedAt"
                      ]
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Validation error (VALIDATION_ERROR) or malformed JSON (INVALID_JSON)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "API key is invalid, disabled, or expired (INVALID_KEY)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded (RATE_LIMITED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Auth or rate limiting not configured (AUTH_UNAVAILABLE, SERVICE_UNAVAILABLE)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/health": {
      "get": {
        "summary": "Health check",
        "description": "Returns API status and available tax years. No authentication required.",
        "operationId": "health",
        "responses": {
          "200": {
            "description": "API is healthy",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "ok"
                      ]
                    },
                    "version": {
                      "type": "string"
                    },
                    "defaultTaxYear": {
                      "type": "string"
                    },
                    "taxYears": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "status",
                    "version",
                    "defaultTaxYear",
                    "taxYears"
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "webhooks": {}
}
