Send household calculation requests over HTTP using PolicyEngine's hosted REST API or the self-hosted Docker image. Use the API guide when you need tokens, endpoints, request bodies, or deployment instructions.
API path
Choose how you want to run the HTTP interface.
Use the hosted PolicyEngine endpoint with OAuth credentials issued by PolicyEngine.
Getting started
The HTTP interface has two paths: the hosted API and the self-hosted Docker image. Start with Docker if you want to make requests immediately on your own machine. Use the hosted API when you want PolicyEngine-managed infrastructure and issued credentials.
Hosted API
Use our managed endpoint with OAuth credentials issued by PolicyEngine.
Docker image
Run the same household API yourself via GitHub Container Registry, without waiting for credentials.
Need direct Python access?
The package guide is now separate from the API docs. Use policyengine[uk] when you want to work locally with calculate_household_impact() or Simulation instead of sending HTTP requests.
Self-hosting the HTTP API on your own machine or infrastructure
None by default
Immediate
Selected access path
The page is currently showing REST API examples. Use the sticky selector above to switch the whole page into a different integration path.
Hosted REST API
Use PolicyEngine's managed HTTP endpoint if you want a hosted integration rather than running the API yourself. This path requires OAuth client credentials issued by PolicyEngine.
Both API paths accept the same household payload and return the same response shape. The difference is whether PolicyEngine hosts the endpoint or you run the container yourself.
Current access path: REST API
Send a POST request to the hosted calculate endpoint with your household object and a bearer token.
POST https://household.api.policyengine.org/uk/calculate
The request body must contain a household key with your household object. The response returns the same structure with all computable variables filled in under the top-level result field.
The request body carries a household object that describes the people and their groupings for tax and benefit calculations. This structure is the same whether you call the hosted endpoint or the Docker container.
Level
Description
Example
Entity group
Top-level grouping category
"people", "benunits"
Entity
Named instance within a group
"person", "my household"
Variable
Property of an entity
"employment_income", "income_tax"
Year
Time period for the value
"2026"
Value
Number, string, boolean, or null for outputs
30000, 9600, null
Entity groups
Most UK household calculations use three entity groups. Each group contains named entities that reference people by name:
Group
Purpose
people
Individual people in the household
benunits
Benefit units used for means-tested benefits
households
Physical household for housing costs and household-level outputs
Step 1: Start with empty groups
Empty household skeleton
{"people":{},"benunits":{},"households":{}}
Step 2: Add people and assign to groups
Create named people and assign them to each UK entity group via the members array. Benefit units and households both reference people by name.
Set input variables as {"year": value} pairs. For outputs you want calculated, set the value to null. The API computes the output variables you request this way.
Putting it all together: a UK family with two children, £40,000 combined employment income, and annual housing costs of £9,600, calculating Child Benefit.
Current access path: REST API
Complete Child Benefit calculation via hosted REST API
Use variable names as keys in your household object, and parameter names to explore the policy rules that drive the simulation. Browse the full list in the model explorer.
Review the terms that govern access to the PolicyEngine API before requesting credentials, integrating the hosted endpoint, or self-hosting the same interface.
