PolicyEngine household API

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.

Open Python package guide

Option	Best for	Authentication	Wait time
Hosted API	Managed infrastructure and remote HTTP access	OAuth client credentials	Requires requesting access
Docker image	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.

Contact hello@policyengine.org to request API credentials.

Fetch an access token

curl --request POST \
  --url https://policyengine.uk.auth0.com/oauth/token \
  --header 'Content-Type: application/json' \
  --data '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "audience": "https://household.api.policyengine.org",
    "grant_type": "client_credentials"
  }'

Fetch an access token in Python

import requests

response = requests.post(
    "https://policyengine.uk.auth0.com/oauth/token",
    json={
        "client_id": "YOUR_CLIENT_ID",
        "client_secret": "YOUR_CLIENT_SECRET",
        "audience": "https://household.api.policyengine.org",
        "grant_type": "client_credentials",
    },
)

token = response.json()["access_token"]

Token response

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6...",
  "token_type": "Bearer"
}

Running a calculation

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.

Hosted API request

curl --request POST \
  --url https://household.api.policyengine.org/uk/calculate \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "household": {
    "people": {
      "person": {
        "age": {
          "2025": 30
        },
        "employment_income": {
          "2025": 30000
        }
      }
    },
    "benunits": {
      "benunit": {
        "members": [
          "person"
        ]
      }
    },
    "households": {
      "household": {
        "members": [
          "person"
        ]
      }
    }
  }
}'

Household payloads

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	"2025"
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.

Two parents with 2 children

{
  "people": {
    "parent_1": {},
    "parent_2": {},
    "child_1": {},
    "child_2": {}
  },
  "benunits": {
    "family": {
      "members": [
        "parent_1",
        "parent_2",
        "child_1",
        "child_2"
      ]
    }
  },
  "households": {
    "home": {
      "members": [
        "parent_1",
        "parent_2",
        "child_1",
        "child_2"
      ]
    }
  }
}

Step 3: Add variables and values

Set input variables as {"year": value} pairs. For outputs you want calculated, set the value to null (or simply omit the variable: all computable variables are returned by default).

With income, ages, and housing costs

{
  "people": {
    "parent_1": {
      "age": {
        "2025": 35
      },
      "employment_income": {
        "2025": 25000
      }
    },
    "parent_2": {
      "age": {
        "2025": 33
      },
      "employment_income": {
        "2025": 15000
      }
    },
    "child_1": {
      "age": {
        "2025": 8
      }
    },
    "child_2": {
      "age": {
        "2025": 5
      }
    }
  },
  "benunits": {
    "family": {
      "members": [
        "parent_1",
        "parent_2",
        "child_1",
        "child_2"
      ]
    }
  },
  "households": {
    "home": {
      "members": [
        "parent_1",
        "parent_2",
        "child_1",
        "child_2"
      ],
      "housing_costs": {
        "2025": 9600
      }
    }
  }
}

Full example: Child Benefit calculation

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

import requests

token = "YOUR_ACCESS_TOKEN"

household = {
    "people": {
        "parent_1": {
            "age": {
                "2025": 35
            },
            "employment_income": {
                "2025": 25000
            }
        },
        "parent_2": {
            "age": {
                "2025": 33
            },
            "employment_income": {
                "2025": 15000
            }
        },
        "child_1": {
            "age": {
                "2025": 8
            }
        },
        "child_2": {
            "age": {
                "2025": 5
            }
        }
    },
    "benunits": {
        "family": {
            "members": [
                "parent_1",
                "parent_2",
                "child_1",
                "child_2"
            ]
        }
    },
    "households": {
        "home": {
            "members": [
                "parent_1",
                "parent_2",
                "child_1",
                "child_2"
            ],
            "housing_costs": {
                "2025": 9600
            }
        }
    }
}

response = requests.post(
    "https://household.api.policyengine.org/uk/calculate",
    json={"household": household},
    headers={"Authorization": f"Bearer {token}"},
)

result = response.json()["result"]
child_benefit = result["benunits"]["family"]["child_benefit"]["2025"]
print(f"Child Benefit: {child_benefit:,.2f}")

Variables and parameters

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.

Explore variables and parameters →

API terms and conditions

Review the terms that govern access to the PolicyEngine API before requesting credentials, integrating the hosted endpoint, or self-hosting the same interface.

Read API terms and conditions →