API requests, responses and specification

Use the calculation reference

This reference describes the inputs and responses for IsMyPayRight’s UK pay calculation endpoints. Start with the operation that matches your question, then open its request schema to check the required fields, supported values and example response. The OpenAPI specification is available directly as JSON, including when the interactive viewer cannot load.

Documented API operations

  • POST /api/v1/calculate: Calculate take-home pay

    Full UK PAYE calculation including income tax, NI, student loans, pension, and salary sacrifice.

  • POST /api/v1/check: Check a payslip

    Validates payslip figures against expected HMRC calculations and identifies discrepancies.

  • POST /api/v1/reverse: Reverse-calculate gross from net

    Given a target net pay, calculates the gross salary required to achieve it. targetNet follows the frequency set in options.frequency.

  • POST /api/v1/pro-rata: Pro-rata salary calculator

    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.

  • POST /api/v1/two-jobs: Two-jobs tax calculator

    Calculates combined tax for two jobs including NI overpayment estimates.

  • POST /api/v1/statutory-pay: Statutory pay calculator

    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.

  • POST /api/v1/mortgage: Mortgage affordability calculator

    Estimates borrowing range, repayments, stress test, and affordability verdict.

  • GET /api/v1/health: Health check

    Returns API status and available tax years. No authentication required.

Check the assumptions before comparing results

Use the tax year and UK region that apply to the calculation. Enter the pay frequency, pension, student-loan and salary-sacrifice details supported by the selected operation rather than assuming that every endpoint accepts the same fields. A monthly payment, annual salary and target net amount answer different questions. Keep the original assumptions alongside a result so another calculation can be reproduced on the same basis.

Read the response schema and documented errors before building an integration. Input validation, authentication and request limits are separate from the calculation itself; the specification shows the operation’s declared requirements. This reference does not issue credentials or create a paid service agreement. For calculation rules, rounding and limitations, use our methodology and sources.

Prefer a web tool for an individual pay question?

The take-home pay calculator provides an interactive way to explore a salary. Use the payslip checker when you have a payslip to examine, or the reverse tax calculator to work backwards from a take-home target. These pages explain the figures alongside their controls and do not require an API integration.