Area Median Income API Percentage

Purpose: Calculates HUD Area Median Income (AMI) as a percentage based on the HUD Median Income dataset.

This calculates the Area Median Income on a Statewide Level and on a County/Entity/MetroArea level. The more local number will require you to have a FIPS code set in your county lookup. FIPS codes are unique codes on the County lookup.

Cost: There is no cost to use this module.


Setting up AMI API calculations requires three steps:

1. Obtaining a HUD API key by following the instructions on the HUD FRM IL Dataset API Documentation page.

2. Entering the HUD API key on the Admin -> Process Settings page and enabling the HUD Median Income Percentage API.

3. Adding the HUD Median API block to your intake process.

Notes on Block Placement

AMI Percentage is calculated by the block by comparing the matter's intake date, county of residence, and total income to HUD's data.

Therefore to get the calculated default, the block needs to be on a form after State, County of Residence, Household Size, and Income have been saved. The block is typically placed on an intake form, and an auxiliary form for editing/recalculation after a case is opened.

If this is configured, the AMI Poverty Category block gets a checkbox in its configuration to "Use HUD Median Income API". When this is selected, it will set the AMI Poverty Category as a result of the API calculation. Note that this is happening as a result of the percentage, so in locations where the standard is not at 30%, 50% or 80%, the selections made will not be accurate. The AMI Poverty Category block needs to come after the HUD Median API block.

The block will cause an error on case profile pages. Only use it on forms.


The statewide calculation should work in every state. It will not work in DC.

The API only returns results for 2017 and later. Earlier intake dates will result in an error of Invalid Year.

The Area level calculation will work in DC. The Area level calculation will not work in Massachusetts or Maine because HUD divides those states up into entities that are based on the Town level and not the county level. Additional development work will be needed to make it work in those states and it will likely require GIS to work there once that development has been done.

Notes on the Calculation

The API takes parameters for the State/County of Residence and the year (based on the Intake Date). Once the State/County limit is returned, the Total Household Income is compared to the HUD Median Income and a percentage is calculated. Household size is taken into account based on the US HUD PDR-99-02 Notice regarding family size adjustments. The number in the HUD dataset is for a family of 4. For smaller families, 10% is removed per person. For larger families 8% is added.