UK Benefits Calculator API

Version 1.0.0

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

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

A stateless RESTful API using central 2026/27 benefit rates for UK benefit estimates. The 2026/27 datasets include council tax figures for England, Scotland and Wales, Northern Ireland domestic poundages, and LHA data in weekly and monthly forms. Local working-age CTR schemes remain labelled 2025/26. Billing-authority council tax figures may average parish precepts and are not exact household bills; Scottish figures exclude water charges. Northern Ireland calculations use the actual domestic rates bill or capital valuation, not council tax bands. 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
Calculations
Rates
Questions
              Data schemas
            
          
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
      
Tier Rate Limit
Unauthenticated 5 requests per minute
Authenticated (default) 100 requests per hour

          
          

          
    

      
        
          Status
          Description
          Schema
        
      
      
        200
        API metadata
        ApiRoot

Tier	Rate Limit
Unauthenticated	5 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 central 2026/27 benefit rates and provenance for the 2026/27 council tax, Northern Ireland domestic poundage and LHA datasets used in calculations. LHA data is available in weekly and monthly forms; local working-age CTR schemes remain labelled 2025/26. Council tax figures may average parish precepts and are not exact household bills, and Scottish figures exclude water charges. Northern Ireland uses domestic rates bills or capital valuations rather than council tax bands. 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. 2026/27
    

          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. For a Northern Ireland private renter, provide `niBrmaCode` as the BRMA code returned by the official NIHE Local Housing Allowance lookup; do not infer it from a postcode or council area. If the area cannot be established, send `niBrmaCode: "unknown"` explicitly (or omit it for legacy clients); the housing element and Housing Benefit estimate are then safely excluded. An explicit `country: "northern-ireland"` must agree with a BT postcode, and a BT postcode must not be paired with an explicit England, Scotland or Wales country. The non-UI system field `assessmentDate` (YYYY-MM-DD) is accepted to make age-dependent calculations reproducible. For LCWRA, set `lcwraProtectedRate` to `yes` or `no` only for an LCWRA determination; terminally ill claimants use the protected rate automatically. If omitted or `not-sure`, the calculator uses the conservative new-claim rate and explains this in the result notes. For UC's first-child element, provide `firstChildDateOfBirth` when known.
    

                  niBrmaCode
      "201" | "202" | "203" | "204" | "205" | "206" | "207" | "208" | "unknown"
      Official NIHE BRMA code for a Northern Ireland private renter, or "unknown" when the area is not known. Areas: 201 South, 202 North, 203 Lough Neagh Lower, 204 North West, 205 South West, 206 South East, 207 Lough Neagh Upper, 208 Belfast.
    
    
    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
    

              dataSources
      object
      Available local dataset versions and provenance. Individual benefit notes identify user-supplied amounts, unmatched postcodes and estimates.
    

      meta
      object
      
    

          calculatedAt
      string (date-time)
      
    

          taxYear
      string
       e.g. 2026/27
    

          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. 2026-27
    

          attributes
      object
      Benefit rate categories and their values in GBP
    

      meta
      object
      
    

          taxYear
      string
       e.g. 2026/27
    

          dataSources
      object
      Local dataset versions, official sources, retrieval dates and coverage limitations. This describes available data, not a guarantee that every dataset was used in an individual award.
    

          rateMetadata
      object
      Machine-readable units, frequencies and explicit exceptions for the central rate payload.
    

              units
      object
      
    

              exceptions
      object
      
    
    
    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.

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. 2026/27
standards	`string`	e.g. https://www.gov.uk/guidance/gds-api-technical-and-data-standards

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. For a Northern Ireland private renter, provide `niBrmaCode` as the BRMA code returned by the official NIHE Local Housing Allowance lookup; do not infer it from a postcode or council area. If the area cannot be established, send `niBrmaCode: "unknown"` explicitly (or omit it for legacy clients); the housing element and Housing Benefit estimate are then safely excluded. An explicit `country: "northern-ireland"` must agree with a BT postcode, and a BT postcode must not be paired with an explicit England, Scotland or Wales country. The non-UI system field `assessmentDate` (YYYY-MM-DD) is accepted to make age-dependent calculations reproducible. For LCWRA, set `lcwraProtectedRate` to `yes` or `no` only for an LCWRA determination; terminally ill claimants use the protected rate automatically. If omitted or `not-sure`, the calculator uses the conservative new-claim rate and explains this in the result notes. For UC's first-child element, provide `firstChildDateOfBirth` when known.
niBrmaCode	`"201" \| "202" \| "203" \| "204" \| "205" \| "206" \| "207" \| "208" \| "unknown"`	Official NIHE BRMA code for a Northern Ireland private renter, or "unknown" when the area is not known. Areas: 201 South, 202 North, 203 Lough Neagh Lower, 204 North West, 205 South West, 206 South East, 207 Lough Neagh Upper, 208 Belfast.

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

UK Benefits Calculator API

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/`

Responses

GET `/api/v1/health`

Responses

Calculations

POST `/api/v1/calculations`

Responses

Rates

GET `/api/v1/rates`

Responses

Questions

GET `/api/v1/questions`

Responses

POST `/api/v1/questions/applicable`

Responses

Data schemas

ApiRoot

HealthResponse

CalculationRequest

CalculationResponse

BenefitResult

IncomeSummary

RatesResponse

QuestionsResponse

QuestionSection

Question

ApplicableQuestionsRequest

ErrorResponse

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

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

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

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

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.

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

Field	Type	Description
data	`array of QuestionSection`
meta	`object`
totalSections	`integer`

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`

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`

UK Benefits Calculator API

MCP ServerThis 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/

Responses

GET /api/v1/health

Responses

Calculations

POST /api/v1/calculations

Responses

Rates

GET /api/v1/rates

Responses

Questions

GET /api/v1/questions

Responses

POST /api/v1/questions/applicable

Responses

Data schemas

ApiRoot

HealthResponse

CalculationRequest

CalculationResponse

BenefitResult

IncomeSummary

RatesResponse

QuestionsResponse

QuestionSection

Question

ApplicableQuestionsRequest

ErrorResponse

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

GET `/api/v1/`

GET `/api/v1/health`

POST `/api/v1/calculations`

GET `/api/v1/rates`

GET `/api/v1/questions`

POST `/api/v1/questions/applicable`