Enrich new HubSpot contacts with Census neighborhood data

Build me an agent workflow that enriches new HubSpot contacts with US Census neighborhood demographics so my sales reps can segment and prioritize inbound leads.

Trigger: a HubSpot webhook subscription on the Contacts object, firing when a new contact is created or when the mailing address fields (street, city, state, ZIP, country) are populated or changed. The payload gives us the contact ID, which the agent uses to fetch the current contact record from HubSpot.

What the agent should do on each run:

1. Read the contact's mailing street, city, state, ZIP, and country from HubSpot. If the country is not the United States, or if the street, city, state, and ZIP are not all present, skip the enrichment and use HubSpot's Create Note to attach a brief note on the contact explaining why we skipped (for example, "Skipped Census enrichment: address outside the US" or "Skipped Census enrichment: missing street or ZIP"). Then stop.

2. Call the US Census "Get Census Geographies by Address (Structured)" operation with the structured street, city, state, and ZIP. Use the Current benchmark and a current ACS vintage so we get a tract code that ACS5 will recognize. From the response, extract the state FIPS, county FIPS, tract code, and ideally the CBSA name.

3. If the geocoder returns no match, use HubSpot's Create Note to attach a short note on the contact saying the address could not be located by the Census geocoder, then stop. Do not fail the run.

4. With a tract in hand, call the US Census "Query American Community Survey 5-Year (ACS5)" operation against the most recent available vintage for that tract. Pull this focused set of variables: median household income (B19013_001E), median home value (B25077_001E), median age (B01002_001E), percent of adults 25+ with a bachelor's degree or higher (derive from B15003), and owner-occupied housing rate (derive from B25003_001E and B25003_002E). The "for" clause should be tract:<tract>, and the "in" clause should be state:<state>+county:<county>.

5. Call HubSpot's "Update Contact" operation on the contact ID, writing the pulled values into custom properties: acs_median_income, acs_median_home_value, acs_median_age, acs_pct_bachelors, acs_owner_occupied_rate, plus acs_tract_geoid and acs_cbsa_name for traceability. Assume these custom properties already exist on Contacts; if any are missing the run should leave a note explaining which ones to create and stop.

6. Call HubSpot's "Create Note" operation and associate the note with the contact. The note body should be a 2-3 sentence plain-English neighborhood summary a rep can read at a glance, like: "Lives in a Census tract with median household income of $X and median home value of $Y. About Z% of adults have a bachelor's degree or higher, and W% of homes are owner-occupied. Part of the <CBSA name> metro." Round numbers, format dollars with commas, and skip any line where the underlying ACS value is null.

Error handling: treat the geocoder no-match case and the non-US case as expected outcomes (log a note, do not fail). Treat HubSpot or Census 5xx errors as retryable; surface anything else as a run failure with a clear message.

Use the HubSpot integration for the trigger, the contact read, the property update, and the note creation. Use the US Census Bureau integration for the address-to-geography lookup and the ACS5 query.