# Better Vetters API

> Better Vetters is a pay-per-call API and MCP server that tells an AI agent whether a US contractor is real, licensed, and pulling permits. It checks official state license boards and city permit portals and returns a verdict, a 0-100 trust score, and the public records behind them. $0.15 per check; every new API key includes starter credits. Public records, not a consumer report.
> Tagline: Vet every contractor in one call.

Better Vetters is operated by James Russell, a sole proprietor based in Waterford, PA. Contact: james@fullyarmedmarketing.com. Site: https://bettervetters.com. API: https://api.bettervetters.com.

## Quick start
1. Get a free API key (includes starter credits): POST https://api.bettervetters.com/v1/keys  with body {"label":"my-agent"}
   New keys use the prefix `bv_live_`. Existing `cc_live_` keys keep working.
2. Check a contractor: POST https://api.bettervetters.com/v1/contractor/check
   Header: Authorization: Bearer <api key>
   Body: {"name":"Acme Roofing LLC","state":"WA","city":"Seattle"}  (optional: license_number, phone, website)
3. Read `verdict`, `trust_score` (0-100 or null), `match.confidence` (0-1), `reasons[]`, `license`, `permits`, `discipline`, `data_freshness`.

## Key facts
- Coverage today: Washington State (L&I contractor licenses, insurance and bond, Seattle permits), Texas (TDLR trade licenses, Austin permits), New York City (DCWP home-improvement licenses and charges, DOB permits). Requests for other states return `out_of_coverage` and are not charged. Live counts: https://api.bettervetters.com/v1/coverage
- Verdicts: trusted, likely_ok, caution, high_risk, unknown, not_found, out_of_coverage.
- Not a consumer report. Do not use for employment, credit, insurance, or tenant-screening decisions.
- A missing record is not proof of a problem. Treat match.confidence below 0.8 as a possible match.
- Always cite `data_freshness` timestamps. This is public-record data, not legal advice.

## Billing
- Each check costs $0.15. Balance: GET /v1/credits.
- When credits run out the API returns HTTP 402 with an x402-style body (`accepts[]`, `price_usd`, `top_up`). Credit packs are coming soon; the 402 body says so.
- Credit packs ($10 / $50 / $200) are coming soon. POST /v1/credits/checkout currently returns HTTP 503 with `{"error":"checkout_unavailable"}`. Your free starter credits work now. Free starter credits have no cash value. All credit purchases are final and non-refundable, except where applicable law requires a refund or to correct a duplicate or erroneous charge. Unused credits are not refundable. Credits do not expire while the account is active.
- Send `Idempotency-Key` to make retries free.

## Docs
- OpenAPI 3.1 spec: https://api.bettervetters.com/openapi.json
- Interactive docs: https://api.bettervetters.com/docs
- This file: https://api.bettervetters.com/llms.txt
- Live coverage (free, no key): https://api.bettervetters.com/v1/coverage
- Site docs: https://bettervetters.com/docs
- Pricing: https://bettervetters.com/pricing
- Coverage: https://bettervetters.com/coverage
- Terms: https://bettervetters.com/terms
- Privacy: https://bettervetters.com/privacy

## MCP
A hosted streamable-HTTP MCP endpoint at https://api.bettervetters.com/mcp exposes `check_contractor` and `get_coverage`. Authenticate with `Authorization: Bearer <api key>`. A stdio server is also available at:
- https://api.bettervetters.com/mcp/server.py
- https://api.bettervetters.com/mcp/README