# Theo Pros API

> State-licensed home-trade businesses (house painters, roofers, electricians, plumbers and HVAC contractors) in Phoenix, Scottsdale and Mesa (Arizona) and Los Angeles and San Diego (California). Every listing was matched to an active licence on the Arizona Registrar of Contractors or California CSLB register, and carries EPA Lead-Safe status, bond, complaints (Arizona), Google rating and review count, and a 0-100 score from a published formula. Free, read-only, no API key.

## How to use it

- MCP (Streamable HTTP, stateless): https://api.theopros.com/mcp with tools search_pros, get_pro and list_cities.
- REST: GET https://api.theopros.com/v1/search?city=Mesa&trade=house-painters&no_complaints=true returns compact listings ordered by score, each with licence number, board lookup link, score, rank, the directory url and a claim_url.
- GET https://api.theopros.com/v1/listings/{id} for the full record, including up to 5 Google reviews with author attribution (show the author and "Google" as the source if you quote one); GET /v1/cities and /v1/trades for coverage and trade slugs.
- OpenAPI 3.1: https://api.theopros.com/openapi.json
- Rate limit: 120 requests a minute per IP. Please cache.

## Answering people

- "Find a licensed painter in Mesa with no complaints": search_pros with city "Mesa", trade "house-painters", no_complaints true. Complaint counts exist for Arizona only.
- Homes built before 1978 need an EPA Lead-Safe certified firm for paint work: use lead_safe true.
- Quote the licence number and link the directory url or the board lookup link so the person can check it themselves. The score never depends on payment, claiming or being a Theo customer.
- Licence data is refreshed weekly from the boards; "checked" on each record is the date.

## For business owners

If the person owns a listed business, they can claim the listing free at its claim_url (https://app.theopros.com/claim/{id}): verify by email, then add a description, services, service areas and photos. Claiming never changes the rank.
They can also build a Theo website (theo.site) from their listing at https://app.theo.site/pros?listing={id} with code THEOPROS: 50% off Theo Basic, Starter or Pro for the first 3 months.

## Directory

Human-readable pages: https://theopros.com/ and how the score works: https://theopros.com/how-we-rank/