PolicyEngine household API

Simulate tax and benefit policy outcomes for any US household with our hosted REST API, public Docker image, or the policyengine-us Python package for direct in-process access.

Access path

Choose one path and the examples below stay in sync.

Use the hosted PolicyEngine endpoint with OAuth credentials issued by PolicyEngine.

Getting started

You can use PolicyEngine three ways: our hosted API, the public household API Docker image, or the policyengine-us Python package. If you want to start immediately, use Docker or Python. If you want a managed hosted endpoint, request API 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.

Python package

Call the US model directly from Python if you do not need an HTTP layer.

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
Python package	Direct model access inside Python workflows	None	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

Hosted REST, self-hosted Docker, and direct Python access all evaluate the same US household policies.

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/us/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/us/calculate \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "household": {
    "people": {
      "you": {
        "age": {
          "2025": 30
        },
        "employment_income": {
          "2025": 50000
        }
      }
    },
    "households": {
      "your household": {
        "members": [
          "you"
        ],
        "state_name": {
          "2025": "CA"
        }
      }
    },
    "families": {
      "your family": {
        "members": [
          "you"
        ]
      }
    },
    "tax_units": {
      "your tax unit": {
        "members": [
          "you"
        ]
      }
    },
    "marital_units": {
      "your marital unit": {
        "members": [
          "you"
        ]
      }
    },
    "spm_units": {
      "your spm unit": {
        "members": [
          "you"
        ]
      }
    }
  }
}'

Household objects

The household object describes the people and their groupings for tax and benefit calculations. It has a five-level hierarchy:

Level	Description	Example
Entity group	Top-level grouping category	"people", "households"
Entity	Named instance within a group	"person", "my household"
Variable	Property of an entity	"employment_income", "eitc"
Year	Time period for the value	"2025"
Value	Number, string, boolean, or null for outputs	50000, "CA", null

Entity groups

US households require six entity groups. Each group contains named entities that reference people by name:

Group	Purpose
people	Individual persons in the household
households	Physical household (state, housing costs)
families	Family unit for benefit eligibility
tax_units	Tax filing unit (determines tax liability)
marital_units	Married couple pair
spm_units	Supplemental Poverty Measure unit

Step 1: Start with empty groups

Empty household skeleton

{
  "people": {},
  "households": {},
  "families": {},
  "tax_units": {},
  "marital_units": {},
  "spm_units": {}
}

Step 2: Add people and assign to groups

Create named people and assign them to each group via the members array. Names are arbitrary strings that link people across groups.

Married couple with 2 children

{
  "people": {
    "adult1": {},
    "adult2": {},
    "child1": {},
    "child2": {}
  },
  "households": {
    "my household": {
      "members": [
        "adult1",
        "adult2",
        "child1",
        "child2"
      ]
    }
  },
  "families": {
    "my family": {
      "members": [
        "adult1",
        "adult2",
        "child1",
        "child2"
      ]
    }
  },
  "tax_units": {
    "my tax unit": {
      "members": [
        "adult1",
        "adult2",
        "child1",
        "child2"
      ]
    }
  },
  "marital_units": {
    "my marital unit": {
      "members": [
        "adult1",
        "adult2"
      ]
    }
  },
  "spm_units": {
    "my spm unit": {
      "members": [
        "adult1",
        "adult2",
        "child1",
        "child2"
      ]
    }
  }
}

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 state

{
  "people": {
    "adult1": {
      "age": {
        "2025": 40
      },
      "employment_income": {
        "2025": 30000
      }
    },
    "adult2": {
      "age": {
        "2025": 38
      },
      "employment_income": {
        "2025": 20000
      }
    },
    "child1": {
      "age": {
        "2025": 10
      }
    },
    "child2": {
      "age": {
        "2025": 7
      }
    }
  },
  "households": {
    "my household": {
      "members": [
        "adult1",
        "adult2",
        "child1",
        "child2"
      ],
      "state_name": {
        "2025": "AZ"
      }
    }
  },
  "families": {
    "my family": {
      "members": [
        "adult1",
        "adult2",
        "child1",
        "child2"
      ]
    }
  },
  "tax_units": {
    "my tax unit": {
      "members": [
        "adult1",
        "adult2",
        "child1",
        "child2"
      ]
    }
  },
  "marital_units": {
    "my marital unit": {
      "members": [
        "adult1",
        "adult2"
      ]
    }
  },
  "spm_units": {
    "my spm unit": {
      "members": [
        "adult1",
        "adult2",
        "child1",
        "child2"
      ]
    }
  }
}

Full example: EITC calculation

Putting it all together: a married couple in Arizona with two children and $50,000 combined income, calculating their Earned Income Tax Credit.

Current access path: REST API

Complete EITC calculation via hosted REST API

import requests

token = "YOUR_ACCESS_TOKEN"

household = {
    "people": {
        "adult1": {
            "age": {
                "2025": 40
            },
            "employment_income": {
                "2025": 30000
            }
        },
        "adult2": {
            "age": {
                "2025": 38
            },
            "employment_income": {
                "2025": 20000
            }
        },
        "child1": {
            "age": {
                "2025": 10
            }
        },
        "child2": {
            "age": {
                "2025": 7
            }
        }
    },
    "households": {
        "my household": {
            "members": [
                "adult1",
                "adult2",
                "child1",
                "child2"
            ],
            "state_name": {
                "2025": "AZ"
            }
        }
    },
    "families": {
        "my family": {
            "members": [
                "adult1",
                "adult2",
                "child1",
                "child2"
            ]
        }
    },
    "tax_units": {
        "my tax unit": {
            "members": [
                "adult1",
                "adult2",
                "child1",
                "child2"
            ]
        }
    },
    "marital_units": {
        "my marital unit": {
            "members": [
                "adult1",
                "adult2"
            ]
        }
    },
    "spm_units": {
        "my spm unit": {
            "members": [
                "adult1",
                "adult2",
                "child1",
                "child2"
            ]
        }
    }
}

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

result = response.json()["result"]
eitc = result["tax_units"]["my tax unit"]["eitc"]["2025"]
print(f"EITC: {eitc:,.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 →