Area Median Income API Calculations

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.

Setup

Setting up AMI API calculations requires three steps:

Obtaining a HUD API key by following the instructions on the HUD FRM IL Dataset API Documentation page.
Entering the HUD API key on the Admin -> Process Settings page and enabling the HUD Median Income Percentage API.
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. The AMI Poverty Category block needs to come after the HUD Median API block or it will take the place of the HUD Median API block.

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

Limitations

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

The Area level calculation will not work in New England (Connecticut, Maine, Massachusetts, New Hampshire, Rhode Island, and Vermont) because HUD divides those into Towns not Counties.

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.

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

Invalid Year

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.

Situations with No Income

As of 2024-04-04 on Demo and 2024-04-12 on Live: If Income has not yet been collected, then you will see a message Income has not yet been populated, median income API is unavailable .

If Income was collected but the client reported No Household Income , then the Percentages and bands are all set to 0 or the lowest bracket possible.

If Income has been collected but the client did not provide their income - Income Not Provided , then the percentages and bands are all set to Null or N/A with the message Income has not been provided.

Why Does my AMI Percentage look Lower than my Band?

There are certain jurisdictions that have High Housing Cost adjustments to the AMI Bands that are not present in the Area Median Income number itself. Examples of this include Los Angeles County, CA and New York County, NY. If you refer to the HUD documentation itself, you can see that the 80% number for a family of 4 is $12,300 more than the Area Median Income. This is because the band is adjusted while the AMI itself is not. You can click on the "Click for More Detail" buttons to see the calculations themselves.