Imagine you're a contractor. You've been in business for twenty years, you bought your state-issued certification last year, and it's good through 2027. Then one morning, you get an automated email from the state telling you your certification expires today and you're no longer authorized to work. Except you are. Your active cert is sitting in a drawer with two more years on it.
That's the kind of false-alarm notification that erodes trust in automated government communications — and it's exactly the problem one of our clients, a state regulatory agency that oversees contractor certifications in the construction industry, asked us to solve.
The Challenge
The agency issues certifications that construction contractors are legally required to hold in order to do business in their jurisdiction. Each certificate has a fixed expiration date, and the agency had been using an old system to manage the contractor relationships and send out automated expiration-warning emails. Daily data flowed in from the state's underlying certification platform — but that data only ever included one feed: certificates that were expiring on that day.
Contractors in this state don't renew certificates — they buy new ones. The system was treating every expiration as a problem, even when the contractor was fully covered.
The Solution
We rewrote the daily ingestion logic from the ground up around the Contractor Certificate custom object as the source of truth, replacing a multi-workflow chain with a single custom code action that handles everything in one pass.
Data Flow, End to End
Once per day, the state's certification platform sends a webhook to HubSpot containing the day's combined feed: certs expiring today, certs expiring in 100 days, and certs issued yesterday — all merged into a single JSON payload. The webhook posts to a designated placeholder contact, updating three properties: a batch identifier, the JSON payload itself, and an authentication key. Those three updates trigger the main workflow.
The workflow's custom code action validates the authentication key, parses the JSON, and then — for each certificate in the payload — searches HubSpot for an existing Contractor Certificate record matched by certificate number. If one is found, the record is updated in place. If not, a new record is created. The contractor's contact record is upserted by email in parallel, and an association is established between the cert and the contact. Because the certificate number is the deduplication key, the same cert can pass through the integration multiple times in its lifetime — once when issued, again as it approaches expiration, again on the day it expires — and always end up as a single HubSpot record, updated in place rather than duplicated.
Record Structure
Each contractor certificate lives as one record in a HubSpot custom object with a small, focused schema:
- Certificate number — the primary identifier; used as the dedup key on every update
- Business license number — identifies the certified business, independent of who personally purchased the cert
- Date issued and expiration date — the validity window
-
Is latest for business — a boolean flag identifying the currently-active cert per business license (more on this below)
Each certificate record is associated with the Contact record of the person who purchased it. A contractor with multiple certs over time has multiple cert records, each pointing to their contact — clean lineage, no overwriting.
The Key Innovation
The most important addition is the "is latest for business" flag. After every daily batch, the integration groups every certificate in the system by business license number, sorts each group by expiration date, and flags the latest one true and the rest false. The recalculation runs continuously, on every workflow run, for every business license touched. The flag isn't a one-time tag — it stays accurate as new certs arrive.
This flag exists because of a quirk in how the state's certifications work: contractors don't "renew" certificates, they purchase new ones. A contractor whose 2022 cert is approaching its expiration date may have already bought a 2025 cert under the same business license that doesn't expire until 2027. In the old system, the 2022 cert's expiration date still triggered a warning email — even though the contractor was fully covered.
Now, the reminder workflow runs against the Contractor Certificate object directly and only enrolls records where the latest-for-business flag is true. The 2022 cert in the example has its flag set to false, because a newer cert exists under the same business license. When its expiration date hits, the workflow ignores it and no email goes out. The contractor never gets the false alarm. Only when a contractor's actually-current cert approaches expiration — meaning no newer cert exists under that business license — does the notification fire.
The integration now models the real-world distinction between "this cert has expired" and "this contractor's business is no longer covered" — and only acts on the second.
Email Reminders, the Right Way
With the new architecture in place, the expiration-warning emails were rebuilt to run against the Contractor Certificate custom object instead of against contacts. The enrollment criteria are simple: the cert's expiration date equals today, and its latest-for-business flag is true. The send-email action targets the associated contact of the enrolled cert, which is always exactly one person (the original purchaser). Personalization tokens pull cert-specific details (cert number, expiration date) from the cert object and contact-specific details (name) from the associated contact.
Future expansions are now trivial. The 100-day warning email is the same workflow with a different date filter. An "issued yesterday" welcome email could be added in a few minutes. Because the cert object is the source of truth and the flag handles the active-cert logic, none of these add risk of false alarms.
The Result
After deployment we ran a one-time backfill across the agency's existing certificate inventory — close to 1,400 historical cert records — to correctly populate the latest-for-business flag everywhere. About thirty business licenses had multiple certs on file, exactly the cases that would have generated false alarms under the old system. All cleaned up in a single idempotent script.
From the contractors' perspective: warning emails now arrive only when their actual coverage is genuinely about to lapse. From the agency's perspective: cleaner data, no duplicate records, and an architecture that scales as additional feeds (early warnings, new-cert confirmations, audit reminders) get layered on. From ours: the satisfaction of seeing a tangled two-workflow chain replaced with a single, idempotent, upsert-by-natural-key pattern that gets the business logic right.
The Takeaway
Government-facing automations have a higher cost of being wrong than most consumer-facing systems. A false expiration warning isn't just an annoying email — it can prompt a contractor to stop work, dispatch a confused phone call, or erode trust in the agency's entire communications program. The fix wasn't a louder system or a more aggressive workflow. It was modeling the actual business reality: contractors don't renew certificates, they buy new ones, and the system needs to know the difference.
Sometimes the most valuable thing an integration does isn't adding capability — it's removing wrong assumptions.
If any of this sounds like a problem you're dealing with, we'd love to hear about it. Tapp Network specializes in rebuilding HubSpot integrations around clean architecture and the real business rules underneath. Whether you're a government agency, a regulated business, or anyone running a HubSpot portal that has grown more complicated than it should be, we can help untangle it.
Get in touch with us and let's build something that actually works.
