We built a Boston permit lookup tool — here's why it needed more than a search box

A real estate agent was doing due diligence on a Boston condo and pulled the permit history. The unit had three bedrooms. The permit history had no record of that third bedroom ever being created. The space existed — the permit didn't. That's an illegal conversion, and it's exactly the kind of thing that doesn't surface unless someone thinks to look for it.

The problem wasn't that the information was hidden. It was that the tool Boston uses to serve permit records — ScerIS — makes it genuinely difficult to look. So we built something better.

What ScerIS actually gives you

ScerIS is Boston's official permit document system. When you search an address, it returns scanned PDFs. Not structured data — scanned images of permit applications, one document per record. There's no unit-level filtering. For a six-unit building with a decade of permit history, that's potentially dozens of PDFs to review manually to find the ones that touch a specific unit.

That's not a complaint about the city — it's a document archive, and it works as one. The problem is that real estate due diligence requires a different kind of query: show me everything that has happened to Unit 4B. ScerIS wasn't built for that question.

What Boston's open data portal actually has

While ScerIS stores the historical archive, Boston's Analyze Boston open data portal publishes a separate, structured dataset: "Approved Building Permits." It covers permits issued since 2009, and it's available via API — real structured records with address, permit type, description, declared valuation, approval date, and applicant. Not scanned images. Queryable data.

That dataset is the foundation of what we built. You type in a Boston address, the tool queries the Analyze Boston API, pulls all permit records for that address, and groups them by unit.

The grouping problem

Pulling permit records by address is straightforward. Grouping them by unit is not.

Permit descriptions are written by people, not machines, and people write them however they want. A permit for the same unit might be described as "Unit 4B," "Apt 4B," "4th floor rear," "third floor unit," or simply "condo 3." Some descriptions mention no unit at all. There's no controlled vocabulary.

This is where we used Claude to help. The unit-matching logic needed to handle a wide range of natural-language variations, including edge cases like buildings where floor references don't correspond to the unit number, or addresses where the same unit is referred to by multiple naming conventions across different permit applications over the years. Claude helped us work through the regex patterns and the confidence-scoring approach — records that clearly matched a unit, records that probably matched, and records where there wasn't enough information to assign them at all.

The tool surfaces that confidence level to the user. A permit with "Unit 4B" in the description is a high-confidence match. A permit that says "third floor work" in a building where Unit 4 is on the third floor is a probable match. A permit for general exterior work gets flagged as unassigned — it might apply to every unit, or it might be irrelevant. Hiding that ambiguity would make the tool feel cleaner but less honest.

What the tool also pulls

Beyond the permit history, the tool queries the Boston assessor record for the address. That gives us the official bedroom and bathroom count, property type, year built, and assessed value. We display this alongside the permit history because the combination is what makes the tool useful for due diligence.

A property with an assessor record showing three bedrooms and a permit history with no permitted bedroom conversion is a flag. It doesn't prove anything on its own — permits get lost, work predates the 2009 dataset, assessor records have their own lag — but it's the kind of discrepancy that warrants a follow-up question before closing.

Testing on a real building

We ran the tool against a building on Province Street in Boston. It had 172 permit records since 2009. The raw list is unusable for unit-level due diligence — that's the problem ScerIS has in a different form. The grouped output organized those 172 records by unit in one pass, with confidence levels, and surfaced the assessor data alongside it.

That's the difference between a search box and a tool. A search box returns results. A tool answers the question you actually had.

What's coming next

The next iteration adds an automated disclosure flag: when the assessor bedroom count doesn't match what the permit history supports, the tool surfaces a specific alert rather than leaving the user to make that inference manually. That comparison is already possible from the data we're pulling — it just needs to be surfaced explicitly rather than implied.

We're also looking at what else can be layered on top of the permit history: open code violations, zoning data, building age relative to permit gaps. A property with no permitted work in 15 years isn't necessarily a problem, but it's a different profile than one with consistent maintenance permits across the same period. That context matters when you're trying to understand what you're actually buying.

Why we built this

We work with real estate teams across the Northeast, and permit research is one of those tasks that has always been time-consuming and easy to get wrong. Not because the data doesn't exist — it does, and Boston publishes more of it than most cities — but because accessing it requires navigating systems that weren't designed for the questions practitioners actually need to answer.

That gap between available data and usable data is where we spend a lot of our time. The Boston permit lookup tool is one version of what closing that gap looks like.