agentlookups.ai / docs / Plumbline

Plumbline documentation

Plumbline checks a contractor's license, by license number or business name, in official licensing-board records. Use it before you hire someone, to see what the board's record says about the license on the bid. It works on its website, through an AI assistant over MCP, and as a plain HTTPS API.

What it is and where the data comes from

Every record comes from the agency that issued it: state licensing boards, plus some city and county licensing offices, that publish their rosters as public data. Plumbline covers business licenses and the licenses tradespeople hold in their own name, such as master and journeyman plumbers. Each result names the agency, gives the status in the agency's own words, and dates the record.

Most sources are fetched again every day; a few boards publish on their own nightly or weekly schedule. A failed download can leave an older record in place, so each record carries the date we collected it. Plumbline keeps each downloaded file unchanged, and each record carries the SHA-256 fingerprint (hash) of the file it came from, so it can be checked against its source. The methodology page has the details.

Cost and access

Plumbline is in beta. Lookups are free during beta, with no account and no API key. Features, limits and pricing may change. Rate limits apply.

Connect it

Claude (web and desktop)

Open Settings > Connectors and choose Add custom connector.
Name it Plumbline and paste https://contractors.agentlookups.ai/mcp as the URL.
Leave authentication empty. Plumbline needs none.

Claude Code

claude mcp add --transport http plumbline https://contractors.agentlookups.ai/mcp

ChatGPT and other MCP clients

Add a remote MCP server with the URL https://contractors.agentlookups.ai/mcp, transport Streamable HTTP, no authentication. Menu names differ by client and plan. The server keeps no session and replies with plain JSON. It takes POST only, one JSON-RPC request per POST, with the headers content-type: application/json and accept: application/json, text/event-stream. To test it by hand:

curl -X POST https://contractors.agentlookups.ai/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"check_contractor",
                 "arguments":{"license":"602331","jurisdiction":"CA"}}}'

Plain HTTPS API

No MCP needed. This URL returns California license 602331 as JSON:

https://contractors.agentlookups.ai/v1/check?license=602331&jurisdiction=US-CA

To search by name, send name= in place of license=, with an optional city=. To pick one record from a list of candidates, send entity_id=. /v1/coverage lists every source we index, with its latest snapshot. /llms.txt sums up the service for AI agents.

The tool

check_contractor: finds a license record by license number or business name, narrowed by jurisdiction (a two-letter state code such as CA, the full state name, or a city code such as NYC) and, if you like, the exact city listed on the record. entity_id picks one record from an earlier answer; offset pages through a long list of candidates. Read-only.

Example prompts

Each prompt was run live on September 28, 2026, with the arguments an assistant would send. Board records change, so your answer may differ.

"Is The Home Depot licensed as a contractor in California?"

Call: check_contractor {"name": "The Home Depot", "jurisdiction": "CA"}

Came back: a match. The California Contractors State License Board (CSLB) record for license 602331, a business record, with status "CLEAR" (which Plumbline groups as active), its license classifications, issue and expiry dates, the snapshot date, and a link to CSLB's own license check.

"My plumber is Roto-Rooter in Florida. Are they licensed?"

Call: check_contractor {"name": "Roto-Rooter", "jurisdiction": "FL"}

Came back: candidates. 18 records from the Florida Department of Business and Professional Regulation (DBPR), listed in several cities, and the message "More than one record matched. Use the license number from the bid or contract to disambiguate."

Follow-up: "It's the Orlando office." Call: check_contractor {"name": "Roto-Rooter", "jurisdiction": "FL", "city": "Orlando"}

Came back: a match. DBPR credential record CFC057359 with status "A" (grouped as active), classification CFC, and its expiry date. The answer asks you to check what the classification covers with the agency.

"Check Maryland home improvement license 164285."

Call: check_contractor {"license": "164285", "jurisdiction": "MD"}

Came back: a match. The Maryland Home Improvement Commission (MHIC) record for Transform Sears Home Services LLC, listed in the board's public list of active licenses, with the record's snapshot date (August 30, 2026 for this record). For today's status, use the MHIC lookup the answer links.

"Is Roto-Rooter licensed in Georgia?"

Call: check_contractor {"name": "Roto-Rooter", "jurisdiction": "GA"}

Came back: not covered, with the message "We do not yet cover GA. We do not have its official lookup URL on file; check the jurisdiction's licensing agency directly. Absence from our index is NOT a determination of licensure."

How to read results

The four answer types

Every answer has a result_type:

match: one record. status groups the board's status as active, inactive, suspended or revoked; raw_status is the board's own wording, or, where the board publishes only a list of active licenses, says the record is on that list. The answer also gives the license classification, the expiry date when the board lists one, the snapshot date (as_of), a link to the agency's own lookup, and where to file a complaint with the agency.
candidates: more than one record matched. Narrow it with the license number from the bid or contract, or with the city listed on the record, or call again with one candidate's entity_id. total_candidates and offset page through long lists.
no_match_in_index: we hold no record that matches. The message lists common reasons (a different legal name, a license held under an owner's name, another state), and the answer links the agency's lookup.
jurisdiction_not_covered: we do not index that place yet. When the answer carries a link, its message says exactly what the link is. For some places it is a consumer-protection or licensing-board page, not a license lookup, so pass on the message's own wording.

Fields worth reading

Credential type. Licenses, registrations and bond filings mean different things. credential.kind, credential.label and credential.note say which one a record is. An active record is not proof that the license covers your job.
Confidence. In the service's words: "confidence: verified describes indexed source evidence, not an endorsement or a fresh agency check. A contradicted dispute is unconfirmed."
Checks marked not_checked. A match also lists discipline, court records, liens, permits and business registration. Where we have not indexed one, it says not_checked, and its note says absence there means nothing.
Business registration. Where we index a state's Secretary of State registry (the registries list in /v1/coverage names them), findings.registration reports what it found. Elsewhere it says not_checked. In the service's words: "no_match_in_registry is NOT a determination that a business is unregistered (sole proprietors need none; boards list trade names)."
Contact details. Some boards publish a phone, email or street address for a business. The answer then carries them, with the source and date. Pass them on as what the board's record lists, never as current and checked. Records of individuals never carry contact details.

The service's honesty rules

Plumbline asks every assistant to pass these on and not override them. From its llms.txt, word for word:

A no_match_in_index result is NOT a determination that a business is unlicensed.

We report what the public record says, with its date; the issuing agency's live page is authoritative for today.

We report occupational-license records, including licenses individuals hold in their own name (journeyman/master trades). We NEVER build person dossiers: an individual's page is their one license record as the board publishes it, with no aggregation beyond it, and it is never for any FCRA purpose.

Limits

Not advice. Plumbline shows a license record. It does not tell you whether to hire anyone.
Not a background check. It is not a consumer report under the Fair Credit Reporting Act or any state consumer-reporting law. Do not use it for decisions about employment, credit, insurance or housing.
Not a rating or a score. It does not rank contractors or judge their work.
A no-match proves nothing. It means our index holds no matching record, never that the contractor is unlicensed.
Not a live check with the agency. Each record is as of its snapshot date. The agency's own lookup is the authority for today.
Not every place. Plumbline covers some states and cities, not all, and for some states it indexes only some boards or trades. Some answers say when coverage is partial; not all do. Discipline, court records, liens and permits are often not indexed; an answer marks each one it did not check.
For what Plumbline covers today, see /v1/coverage. Do not rely on a list copied from somewhere else, including this page.

Troubleshooting

State names and codes. Give the jurisdiction as a two-letter code (CA), the full state name (California), or a city code from /v1/coverage such as NYC. Anything else returns the error unrecognized_jurisdiction, which lists the accepted forms. If an answer says "We do not yet cover" and spells out a full state name, ask again with the two-letter code.
Not covered. If the message names a city we cover (for New York state it suggests NYC), ask again with that code. Otherwise check /v1/coverage. If the place is not listed, use that state's or city's own licensing agency.
No match. Try the license number printed on the bid or contract, not the name on the truck. Try the legal business name as written on the contract, or fewer words. Check the state: the license may be held in another state, or under an owner's or qualifier's name. Then use the agency lookup the answer links.
Too many candidates. Add the license number or the city. The city filter matches the city listed on the record exactly; it is not a service area, so a business based in another city drops out.
Error "provide an entity_id, record number or business name". The call had neither a license number nor a name.
HTTP 429. Too many requests from your network address in a short time. Wait, then send requests more slowly.
HTTP 405 from /mcp. The client sent GET. This server takes POST only.
HTTP 400 from /mcp. The request was a batch (a JSON array), or its body was not valid JSON. Send one JSON-RPC request per POST.
A record looks wrong. Use the report form, or email corrections@agentlookups.ai with the license number, the state, what is wrong, and a link to the board's own page if you have one. We check it against the source. While we review it, the record shows as under review; we add a note and do not quietly delete. Corrections are free.
Anything else. Write to support@agentlookups.ai.

Privacy and terms

One privacy page and one set of terms cover all six agentlookups.ai services. In short: no accounts, no cookies, no trackers. The web server logs requests to /search/, /v1 and /mcp without the words you searched (a request that fails partway can leave them in an error line), and deletes its logs after 14 days. A contractor's record page names the contractor in its address, so a visit to one leaves that name in the page log. If you report a record error, we keep the report, and your email address only if you give it.

Plumbline is run by TopHat Monkey Software LLC.

Last updated: September 28, 2026