UK Benefits Calculator API

Version 1.0.0

Base URL: https://missingbenefit.com/api/v1

OpenAPI spec: /api/v1/openapi.json

Licence: Creative Commons Attribution-NonCommercial 4.0 International (CC BY-NC 4.0)

A stateless RESTful API for calculating UK benefit eligibility for the 2025/26 tax year. Covers central government benefits (Universal Credit, State Pension, Pension Credit, PIP, Attendance Allowance, Housing Benefit, ESA, Carer's Allowance, Child Benefit, Winter Fuel Payment, Warm Home Discount, Free TV Licence, NHS Low Income Scheme, Council Tax Reduction), plus devolved and local benefits (Scottish Pension Age Winter Heating Payment, Carer's Allowance Supplement, Funeral Support Payment, Welsh Winter Fuel Support, Northern Ireland Rate Rebate, Discretionary Support). This API follows the GDS API technical and data standards. All endpoints return JSON (application/json; charset=utf-8).

Authentication

Authentication is optional but recommended. Unauthenticated requests are allowed but subject to a strict IP-based rate limit of 5 requests per minute.

To get higher rate limits, register for an API key by creating an account and visiting the API Keys page. Pass your API key in the Authorization header as a Bearer token:

``

Authorization: Bearer bfk_your_api_key_here `

Alternatively, you can use the X-API-Key header:

` X-API-Key: bfk_your_api_key_here `

Rate Limiting

Rate limit information is returned in the response headers:

- X-RateLimit-Limit — your request limit - X-RateLimit-Remaining — requests remaining in the current window

If you exceed your rate limit, you will receive a 429 Too Many Requests` response. Wait for the window to reset before making more requests.

MCP Server

This calculator also exposes a Model Context Protocol (MCP) server for AI assistant integration. See the MCP Server documentation for details.

Endpoints

Service

GET /api/v1/

API root

Returns metadata about this API including available endpoints and links to documentation.

Example curl request 
curl https://missingbenefit.com/api/v1/ \
  -H "Authorization: Bearer bfk_your_api_key_here"

Responses

TierRate Limit
Unauthenticated5 requests per minute
Authenticated (default)100 requests per hour
Status Description Schema
200 API metadata ApiRoot

GET /api/v1/health

Health check

Returns the health status of the API. Use this to monitor availability.

Example curl request 
curl https://missingbenefit.com/api/v1/health \
  -H "Authorization: Bearer bfk_your_api_key_here"

Responses

Status Description Schema
200 Service is healthy HealthResponse

Calculations

POST /api/v1/calculations

Create a benefit calculation

Submit questionnaire answers and receive a full benefit eligibility calculation. The request is stateless — no data is stored. All monetary values are in GBP per month unless stated otherwise. Dates should be provided as objects with day, month, and year string properties (e.g. {"day":"15","month":"5","year":"1990"}).

Request body: CalculationRequest (application/json)

Example: Working-age single person 
{
  "data": {
    "type": "calculation",
    "attributes": {
      "answers": {
        "dateOfBirth": {
          "day": "15",
          "month": "5",
          "year": "1990"
        },
        "postcode": "SW1A 2AA",
        "relationshipStatus": "single",
        "hasChildren": "no",
        "housingStatus": "renting-private",
        "weeklyRent": "120",
        "employmentStatus": "unemployed",
        "monthlyEarnings": "0",
        "hasOtherIncome": "no",
        "savingsAmount": "under-6000",
        "hasHealthCondition": "no",
        "isCarer": "no"
      }
    }
  }
}
Example: Pensioner on Pension Credit 
{
  "data": {
    "type": "calculation",
    "attributes": {
      "answers": {
        "dateOfBirth": {
          "day": "10",
          "month": "3",
          "year": "1955"
        },
        "postcode": "LS1 4AP",
        "relationshipStatus": "single",
        "receivingStatePension": "yes",
        "niQualifyingYears": "30-34",
        "privatePensionIncome": "50",
        "receivingPensionCredit": "yes",
        "hasChildren": "no",
        "housingStatus": "renting-social",
        "weeklyRent": "100",
        "councilTaxExempt": "no",
        "councilTaxBand": "B",
        "employmentStatus": "retired",
        "hasOtherIncome": "no",
        "savingsAmount": "under-6000",
        "hasHealthCondition": "yes",
        "dailyLivingDifficulty": "moderate",
        "nightTimeCareNeeds": "no",
        "terminallyIll": "no",
        "mobilityDifficulty": "mild",
        "isCarer": "no",
        "livingArrangement": "alone",
        "heatingType": "gas"
      }
    }
  }
}

Responses

Status Description Schema
201 Calculation created successfully CalculationResponse
400 Invalid request body ErrorResponse
401 Unauthorized — missing or invalid API key ErrorResponse
429 Rate limit exceeded ErrorResponse
500 Internal server error ErrorResponse
Example 401 response 
{
  "errors": [
    {
      "status": "401",
      "title": "Unauthorized",
      "detail": "Invalid API key. Check your key or generate a new one at /api-keys."
    }
  ]
}
Example 429 response 
{
  "errors": [
    {
      "status": "429",
      "title": "Too Many Requests",
      "detail": "You have exceeded the rate limit of 100 requests per hour. Please wait before making more requests."
    }
  ]
}

Rates

GET /api/v1/rates

List benefit rates

Returns the current 2025/26 benefit rates used in all calculations. Rates are updated annually. All monetary values are in GBP.

Example curl request 
curl https://missingbenefit.com/api/v1/rates \
  -H "Authorization: Bearer bfk_your_api_key_here"

Responses

Status Description Schema
200 Benefit rates for the current tax year RatesResponse
401 Unauthorized — missing or invalid API key ErrorResponse
429 Rate limit exceeded ErrorResponse

Questions

GET /api/v1/questions

List questionnaire sections

Returns all questionnaire sections and their questions. Use this to understand which answer keys the /calculations endpoint expects, or to build your own front end.

Example curl request 
curl https://missingbenefit.com/api/v1/questions \
  -H "Authorization: Bearer bfk_your_api_key_here"

Responses

Status Description Schema
200 All questionnaire sections QuestionsResponse
401 Unauthorized — missing or invalid API key ErrorResponse
429 Rate limit exceeded ErrorResponse

POST /api/v1/questions/applicable

Get applicable questions for given answers

Returns only the sections and questions that apply based on the answers provided so far. Some sections are conditional — for example, the partner section only appears when the relationship status is 'couple'. Use this to build a progressive questionnaire.

Request body: ApplicableQuestionsRequest (application/json)

Example request body 
{
  "data": {
    "type": "question-filter",
    "attributes": {
      "answers": {
        "relationshipStatus": "couple",
        "hasChildren": "yes"
      }
    }
  }
}

Responses

Status Description Schema
200 Applicable questionnaire sections QuestionsResponse
400 Invalid request body ErrorResponse
401 Unauthorized — missing or invalid API key ErrorResponse
429 Rate limit exceeded ErrorResponse

Data schemas

ApiRoot

Field Type Description
data object
    type string e.g. api
    id string e.g. uk-benefits-calculator
    attributes object
        name string e.g. UK Benefits Calculator API
        version string e.g. 1.0.0
        description string
links object
    self string e.g. /api/v1
    documentation string e.g. /api-docs
    openapi string e.g. /api/v1/openapi.json
    calculations string e.g. /api/v1/calculations
    rates string e.g. /api/v1/rates
    questions string e.g. /api/v1/questions
    health string e.g. /api/v1/health
meta object
    taxYear string e.g. 2025/26
    standards string e.g. https://www.gov.uk/guidance/gds-api-technical-and-data-standards

HealthResponse

Field Type Description
data object
    type string e.g. health
    id string e.g. api-health
    attributes object
        status "ok" | "degraded" | "critical" e.g. ok
        uptime number Uptime in seconds
meta object
    timestamp string (date-time)

CalculationRequest

Field Type Description
data required object
    type required "calculation"
    attributes required object
        answers required object Key-value pairs of questionnaire answers. Use /questions to see all valid keys.

CalculationResponse

Field Type Description
data object
    type string e.g. calculation
    id string (uuid)
    attributes object
        totalMonthly number Total monthly benefit amount in GBP (excludes annual-only benefits)
        totalAnnual number Total annual benefit amount in GBP (from monthly benefits, i.e. totalMonthly × 12)
        totalAnnualBenefits number Total of annual-only benefits in GBP (e.g. Winter Fuel Payment). Add to totalAnnual for the complete yearly figure.
        benefits array of BenefitResult
        incomeSummary object A breakdown of all income sources identified from the user's answers, used in means-tested benefit calculations.
            lines array of object
            totalMonthlyIncome number Total monthly income in GBP across all sources
            isCouple boolean Whether the calculation is for a couple
meta object
    calculatedAt string (date-time)
    taxYear string e.g. 2025/26
    disclaimer string
    warnings array of object Present only if the request contained unrecognised answer fields.

BenefitResult

Field Type Description
id string e.g. universal-credit
name string e.g. Universal Credit
eligible boolean
monthlyAmount number Monthly amount in GBP (0 for annual-only benefits)
annualAmount number Annual amount in GBP
description string
breakdown array of object Line-by-line breakdown of how the amount was calculated. Present only for eligible benefits with detailed calculations.
applyUrl string (uri) GOV.UK URL where the user can apply for this benefit
notes array of string Explanatory notes about eligibility or calculation assumptions
councilName string Name of the local council. Present only for council-specific benefits such as Council Tax Reduction.
paymentFrequency "monthly" | "annual" How often this benefit is paid. Defaults to monthly if not specified. Annual benefits (e.g. Winter Fuel Payment) are excluded from totalMonthly.
eligibilityLabel string A short label describing the eligibility status, e.g. 'Currently receiving'. Present only for certain benefits like State Pension.

IncomeSummary

A breakdown of all income sources identified from the user's answers, used in means-tested benefit calculations.

Field Type Description
lines array of object
totalMonthlyIncome number Total monthly income in GBP across all sources
isCouple boolean Whether the calculation is for a couple

RatesResponse

Field Type Description
data object
    type string e.g. rates
    id string e.g. 2025-26
    attributes object Benefit rate categories and their values in GBP
meta object
    taxYear string e.g. 2025/26

QuestionsResponse

Field Type Description
data array of QuestionSection
meta object
    totalSections integer

QuestionSection

Field Type Description
type string e.g. question-section
id string e.g. about-you
attributes object
    title string
    description string
    questions array of Question

Question

Field Type Description
id string
type "radio" | "text" | "number" | "date" | "select" | "currency" | "children-editor" | "children-sex-editor" | "children-disability-editor"
label string
hint string
options array of object
required boolean

ApplicableQuestionsRequest

Field Type Description
data required object
    type required "question-filter"
    attributes required object
        answers required object Current answers to filter questions by

ErrorResponse

Field Type Description
errors array of object

Also available: MCP Server documentation for AI assistant integration.