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.

Frequently asked questions

How do you look up building permits for a Boston address?

The City of Boston's official permit search is ScerIS, which returns scanned PDF documents with limited filtering. For a more usable lookup, Boston's Analyze Boston open data portal publishes a structured 'Approved Building Permits' dataset via API covering permits issued since 2009. You can query it by address and get all permit records as structured data, though the results require additional parsing to group by unit in multi-family buildings.

What is ScerIS and why is it hard to use for Boston permit research?

ScerIS is Boston's official document management system for building permits. It stores permit records as scanned images, meaning search results are PDF documents rather than structured data. There is no unit-level filtering, so researching a multi-family building requires reviewing every permit record for the entire address to find the ones relevant to a specific unit. For properties with dozens or hundreds of units, this is time-consuming and easy to miss.

What is the Analyze Boston permits API?

Analyze Boston is the City of Boston's open data portal. Its 'Approved Building Permits' dataset contains structured permit records, address, permit type, description, applicant, approval date, declared valuation, going back to 2009. The dataset is available as a queryable API, which means it can be searched programmatically by address without manually reviewing scanned documents. It covers permitted work but not historical records predating 2009.

How can you tell if a Boston property has unpermitted bedrooms?

Comparing the assessor record (which lists the official bedroom count for a property) against the permit history can surface discrepancies. If an assessor record shows three bedrooms but permit history shows no permitted work converting a space to a bedroom, the unit may have been illegally converted. Boston's Analyze Boston dataset and the city's assessor database are both queryable, making it possible to automate this comparison, though permit descriptions vary in quality, and a discrepancy warrants further investigation rather than a definitive finding.

Does Boston's open data portal cover all building permits?

The Analyze Boston 'Approved Building Permits' dataset covers permits issued since 2009. Permits issued before that date are in ScerIS as scanned documents and are not in the structured dataset. For older properties, a complete permit history may require reviewing both sources. The dataset also reflects approved permits, it does not indicate whether permitted work was actually completed or passed final inspection.