Sync new Addepar households into HubSpot every Monday

Every Monday at 7am, sync new households from Addepar into HubSpot so client operations stays in lockstep with the wealth platform. This runs on a cron trigger because Addepar does not emit webhooks and is not a supported poll source, so a weekly sweep is the right shape.

Step 1 — pull households and clients from Addepar. Use Addepar List Entities to fetch household and client entities that were created or last updated since the previous run. Group clients under their household. For each household, use Addepar Query Portfolio Data to fetch the latest total assets under management (a market value column, as of today), plus any household attributes the firm uses to bucket clients (advisor owner, region, segment).

Step 2 — check HubSpot for existing records before creating anything. For each Addepar household, look up existing HubSpot contacts by the primary client's email (exact match) and by name (fuzzy match on first + last, tolerating minor spelling variations, nickname vs. legal name, and prefix/suffix differences). Do the same for HubSpot companies against the household name. If a close but not identical match already exists, skip the create and flag it as a suspected duplicate — do not auto-merge. Treat an exact email match on the primary client as the same person and update rather than create.

Step 3 — write into HubSpot. Use HubSpot Batch Upsert Contacts (matched on email) to create or update a contact for each household's primary client. Set the Addepar entity ID as a unique custom property on the contact so future runs can match on it directly and never double-create. Enrich the contact with lifecycle stage and the advisor owner sourced from the Addepar household. Then use HubSpot Create Company to represent the household, populating the company with the household name, the latest total AUM from Query Portfolio Data, and any relevant segmentation attributes. Associate the primary client contact to the household company.

Step 4 — track AUM tier changes. Compare the current AUM to what HubSpot last had for each household company. When a household crosses a tier boundary the firm cares about (for example moving between mass-affluent, HNW, and UHNW bands), note the transition for the summary. Tier thresholds should be configurable — start with sensible defaults and let the user tune them.

Step 5 — post a Slack summary. Use Slack Send a Message to post to the client ops channel with three sections: new households added this run (name, primary client, AUM, advisor owner), households whose AUM tier changed since last run (household, old tier, new tier, delta), and suspected duplicates that need a human decision (Addepar household on one side, closest HubSpot match on the other, plus why it was flagged — email overlap, near-identical name, etc.). Keep the message scannable with clear section headers; the whole point is that a client ops lead can read it over coffee and know what to action.

Guardrails: never write to HubSpot without checking for a close match first. Never delete or archive existing HubSpot records. Prefer updating an existing HubSpot contact over creating a new one when the Addepar entity ID or email matches. If Addepar Query Portfolio Data would run against too many entities to fit inside a single sync call, break the query into batches by household. On errors from any single household, keep going and include the failure in the Slack summary rather than aborting the whole run.